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.

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 & paymentCC.

See credit card payment flow for more details.

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 Credit from type Refund: A request instructing the Gateway to refund a previously settled transaction to the consumer.
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. The voided transaction can either be a Settle, Sale or Credit.
The Void transaction enables you to cancel an erroneous or problematic transaction before it is settled. As the voided transaction is cancelled before it is sent to the acquirer bank, it does not appear in the customer’s credit card statement.
As transactions can only be voided before they are sent to the acquirer bank, it is only possible to process them prior to the daily transmission of transactions to the acquirer bank. Contact SafeCharge Technical Support for the most up-to-date transmission times.
Failing to void a transaction before the daily transmission may lead to the transaction being settled or credited. You cannot void a transaction that has been settled or credited. After a transaction has been settled, you can only refund the cardholder by issuing a refund.



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
getSessionToken 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.).
openOrder 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.
updateOrder This method enables the updating of an order previously opened by a merchant.
getOrderDetails This method allows the return of specific order details based on order ID.
cardTokenization This method enables the creation of a temporary credit card token according to the card data (number, etc.)
paymentCC This method allows to perform payment using credit card.
This is possible via regular payment or reoccurring payment/re-bill.
dynamic3D 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.
payment3D This method enables the credit card payment via 3D secure payment flow. The dynamic3D method must be called before.
paymentAPM This method enables payment using an alternative payment method (not a credit card).
getMerchantPaymentMethods 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.
createSubscription This method is used for creating a subscription for consumers that wish to conduct future recurring transactions based on previous successful transactions.
cancelSubscription This method is used for canceling existing subscriptions.
getSubscriptionsList This method is used for receiving a list of all existing subscriptions.
The results can be filtered by the input parameters.
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
settleTransaction Settle an already authorized transaction (when working in a two-phase auth - settle manner only).
refundTransaction Refund a previously settled transaction.
voidTransaction Void a previously performed authorization transaction.
payout This method allows to perform payout (transfer funds from merchant to consumer, with no relation to previous transaction).
eKYC Enables performing the entire KYC process online.
createUser Creates a user.
updateUser Updates a user’s details.
getUserDetails Retrieves the details for a specific user.
addUPOCreditCard Adds a credit card for a specific user when the credit card token is available.
addUPOCreditCardByToken Adds a credit card for a specific user when the credit card token is available.
addUPOCreditCardByTempToken Adds a credit card for a specific user when the credit card temporary token is available.
addUPOAPM Adds an alternative payment method (APM) to a user’s list of UPOs.
getUserUPOs Returns a list of a user’s payment options.
deleteUPO Deletes a specific payment option from a user’s list of UPOs.
editUPOCC Edits the credit card details for a specific user.
editUPOAPM Edits the APM details for a specific user.
suspendUPO Suspends a user payment option for a specific user.
enableUPO Enables a suspended user payment option for a user.

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 will be available soon.



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

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

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

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
getMerchantPayemntMethods Metedata service to render payment page on merchant side with available payment methods.
openOrder Mandatory
updateOrder Optional
getOrderDetails Optional
paymentAPM Mandatory



Paymentusingapmflow

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
The merchant calls this method from its client side using SafeCharge’s provided JavaScript.
The merchant passes the provided card token from its client side to its server side. This is the merchant’s responsibility.
creteUser 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
The merchant passes the provided card token from its client side to its server side. This is the merchant’s responsibility.
creteUser 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 (done by Mobile SDK)
The merchant passes the provided card token from its client side to its server side. This is the merchant’s responsibility.
creteUser Optional
If user does not exist yet, need to create it in order to later use it in addUPOCreditCardByTempToken.
addUPOCreditCardByTempToken Optional
paymentCC Mandatory



Cardtokenizationpaymentmobilesdkflow

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

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.

Alternative Payment Methods (APM’s) and DMN Notifications

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 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 additional 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, 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 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.
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.
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.
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 are:
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.
upoRegistrationDate No The date that the UPO was registered in the following format: YYYMMDDHHmmss

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
0 (No text in reason parameter since there was no error.)
1000 General Error.
1001 Invalid checksum.
1004 Missing or invalid CardData data.
1007 Invalid name on card.
1010 Invalid user token. Once set user token can not be updated.
1011 Missing or invalid UserPaymentOption data.
1013 Invalid merchant ID.
1014 Invalid country code.
1019 Validation Error.
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.
1075 Invalid language code.



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.

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

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/getSessionToken.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/getSessionToken.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getSessionToken.do
Example Request
1
2
3
4
5
6
7
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "1484759782197",
    "timeStamp": "20170118191622",
    "checksum": "85fe319906f0af443e471e8dc9663ccfaf31a6afe4d1f426e1a8c641c7886db6"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getSessionToken.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/openOrder.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/openOrder.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/openOrder.do
Example Request
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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/openOrder.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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 does 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.
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

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/updateOrder.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/updateOrder.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/updateOrder.do
Example Request
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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/updateOrder.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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 does 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.
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

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 order details of an existing order. Note that order details can be viewed at any point in time.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/getOrderDetails.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/getOrderDetails.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getOrderDetails.do
Example Request
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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getOrderDetails.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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

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
{
    "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"
    },
    "deviceDetails":{
        "deviceType": "UNKNOWN",
        "deviceName": "",
        "deviceOS": "",
        "browser": "",
        "ipAddress": ""
    },
    "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

cardTokenization

This method 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 using the paymentCC method.

This method 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.

Card Tokenization Client SDK: 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:

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:

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:

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:

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.

1
Safecharge.card.createToken(payload, safechargeResultHandler); 

 



Card Tokenization Method

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/cardTokenization.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/cardTokenization.do





Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/cardTokenization.do
Example Request
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":""
    }
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/cardTokenization.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

reqPost.write(jsonObject);
reqPost.end();
reqPost.on('error', function(e) {
    console.error(e);
});
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.
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

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.

paymentCC

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

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/paymentCC.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/paymentCC.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/paymentCC.do
Example Request
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
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "orderId":"39272",
    "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": "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": "5101080963349948",
                "cardHolderName": "test name",
                "expirationMonth": "01",
                "expirationYear": "2020",
                "CVV": "122"
        },
    "userPaymentOption":{
        "userPaymentOptionId":"1459503",
        "CVV":"234"
    },
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/paymentCC.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});

reqPost.write(jsonObject);
reqPost.end();
reqPost.on('error', function(e) {
    console.error(e);
});
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.
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 Yes 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 does 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.
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.
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.
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

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.
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, up to 35 characters, returned for each approved and pending 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.
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.

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:

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/dynamic3D.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/dynamic3D.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/dynamic3D.do
Example Request
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",
    "isDynamic3D": "1",
    "dynamic3DMode":"ON",
    "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"
    },
    "userPaymentOption": "12442",
    "addendums": {
        "localPayment":{
            "nationalId": "012345678",
            "debitType": "1",
            "firstInstallment": "",
            "periodicalInstallment": "",
            "numberOfInstallments": ""
        }
    },
    "urlDetails": {
        "notificationUrl": "http://notificationUrl.com"
    },
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/dynamic3D.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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,
See Description
In case the merchant would like to manage the 3DSecure rule engine using SafeCharge 3DSecure rule engine, then need to send:
isDynamic3D=1 and EXCLUDE the below dynamic3DMode parameter from the request.
dynamic3DMode String No In case the merchant would like to manage the 3DSecure rule engine by himself (and not using SafeCharge 3DSecure rule engine), then need to send:
isDynamic3D=1 and dynamic3DMode=ON in order to force 3DSecure transaction
-OR-
isDynamic3D=1 and dynamic3DMode=OFF in order to force NON-3DSecure transaction
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 does 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
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.
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.
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 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

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
{
    "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",
    "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.
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, up to 35 characters, returned for each approved and pending transaction.
paRequest String The 3D secure request data for the card issuer/bank.
acsUrl String URL/endpoint used to redirect the consumer to the card issuer/bank’s 3D secure verification page.
externalToken Class externalToken_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.



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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/payment3D.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/payment3D.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/payment3D.do
Example Request
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",
    "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"
    },
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/payment3D.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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.
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 does 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.
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.
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 No 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.
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

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.
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, up to 35 characters, returned for each approved and pending 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.
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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/getMerchantPaymentMethods.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/getMerchantPaymentMethods.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getMerchantPaymentMethods.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
{
    "sessionToken": "9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId":"7777777",
    "merchantSiteId":"19",
    "clientRequestId": "1484759782197",
    "currencyCode":"GBP", 
    "countryCode":"GB", 
    "languageCode":"eng", 
    "timeStamp":"20151105021120",
    "checksum":"6133d0fd12e90ff8de5d8ab5e52a8c23"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getMerchantPaymentMethods.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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

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

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/paymentAPM.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/paymentAPM.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/paymentAPM.do
Example Request
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
{
    "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": ""
    },
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/paymentAPM.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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 does 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.
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.
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

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.
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, up to 35 characters, returned for each approved and pending 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 on the web enables a consumers to access payment details that are stored in an e-wallet. If a consumer is using Safari on their iPhone or iPad, when they tap “Buy with Apple Pay” on a merchant’s site, they’ll are shown a modal payment sheet. If the consumer is using Safari on their Mac, and have an iOS device in range, they 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):

1
2
3
4
5
6
7
if (window.ApplePaySession) {
  var merchantIdentifier = 'example.com.store';
  var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
  promise.then(function (canMakePayments) {
  if (canMakePayments) {
  } // Display Apple Pay Buttons here… });
}



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:

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:

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.

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.

Re-bill

Re-bill is performed by sending isRebilling parameter as input to 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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/createSubscription.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/createSubscription.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/createSubscription.do
Example Request
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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/createSubscription.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/cancelSubscription.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/cancelSubscription.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/cancelSubscription.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "userTokenId": "487106",
    "clientRequestId": "12345",
    "subscriptionId": "12345",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/cancelSubscription.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/getSubscriptionsList.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/getSubscriptionsList.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getSubscriptionsList.do
Example Request
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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getSubscriptionsList.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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 No 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 String 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 String 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

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

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/getSubscriptionPlans.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/getSubscriptionPlans.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getSubscriptionPlans.do
Example Request
1
2
3
4
5
6
7
{
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "clientRequestId": "12345",
    "timeStamp": "20170118191845",
    "checksum": "649c79075b9147de12d2b0ff62484a09"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getSubscriptionPlans.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/settleTransaction.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/settleTransaction.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/settleTransaction.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/settleTransaction.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
amount Decimal Yes The transaction amount.
currency String Yes The three character ISO currency code.
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 need to provide a value for this field in order for it to appear in the payment statement.
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 need to provide a value for this field in order for it to appear in the payment statement.
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

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

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/refundTransaction.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/refundTransaction.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/refundTransaction.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/refundTransaction.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
amount Decimal Yes The transaction amount.
currency String Yes The three character ISO currency code.
relatedTransactionId String Yes The ID of the settle 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

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 The authorization code of the related settle 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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/voidTransaction.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/voidTransaction.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/voidTransaction.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/voidTransaction.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
amount Decimal Yes The transaction amount.
currency String Yes The three character ISO currency code.
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

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 The authorization code of the related settle 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).



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/payout.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/payout.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/payout.do
Example Request
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": "8263015379487437770",
    "merchantSiteId": "39",
    "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":"234"
    },
    "comment": "some comment",
    "urlDetails": {
        "notificationUrl": ""
    },
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/payout.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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 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.

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

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

eKYC

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

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/eKYC.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/eKYC.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/eKYC.do
Example Request
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": "19850101143321",
        "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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/eKYC.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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 YYYYMMDDHHmmss 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 or NationalId.
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "merchantId": "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": ""
    }],
    "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.
Possible values include: APPROVED, DECLINED, NONE.
kycServiceDetails Class serviceDescription,
subPoviderDescription,
resultDescription,
referenceId
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 Sting The current version of the request. The current version is 1. 

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/createUser.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/createUser.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/createUser.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39", 
    "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": "",
    "timeStamp": "20150915143321",
    "checksum": "21bc2501b7857059862124a5d04c9ade"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/createUser.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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, timeStamp, merchantSecretKey.

Output Parameters

Example Response

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/updateUser.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/updateUser.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/updateUser.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
     "merchantId": "8263015379487437770",
     "merchantSiteId": "39",
     "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": "",
     "timeStamp": "20150915143421",
     "checksum": "b47f85bf3a06f5971b38b16e74b230a0"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/updateUser.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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, timeStamp, merchantSecretKey.

Output Parameters

Example Response

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/getUserDetails.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/getUserDetails.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getUserDetails.do
Example Request
1
2
3
4
5
6
7
8
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39", 
    "userTokenId": "testUserToken", 
    "clientRequestId": "101",
    "timeStamp": "20150915143921",
    "checksum": "03aab7ddc2d551ee672632c4a3c56902"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getUserDetails.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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

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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/addUPOCreditCard.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCard.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCard.do
Example Request
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": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId":"",
    "clientRequestId": "235", 
    "ccCardNumber": "4111111111111111",
    "ccExpMonth": "12",
    "ccExpYear": "24", 
    "ccNameOnCard": "some name on card",
    "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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOCreditCard.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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

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, MasterCard, 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.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/addUPOCreditCardByToken.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCardByToken.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCardByToken.do
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39", 
    "userTokenId": "487106",
    "clientRequestId": "110",
    "ccExpMonth": "12",
    "ccExpYear": "24", 
    "ccNameOnCard": "John Smith", 
    "ccToken":"ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0A
    TwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA=="   ,
    "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"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOCreditCardByToken.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
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.
ccToken String Yes A hashed value of the credit card number.
brand String Yes The brand of the credit card, i.e. Visa, MasterCard, etc.
uniqueCC String Yes A unique identifying code for the credit card.
bin String Yes The credit card’s bin number.
last4Digits String Yes The last four digits of the credit card number.
billingAddress Class No firstName,
lastName,
address,
phone,
zip,
city,
countryCode(two-letter ISO country code),
state(two-letter ISO state code),
email,
county
lastDepositUse String No The last deposit use.
lastDepositSuccess String No The last deposit success.
lastWithdrawalUse String No The last withdrawal use.
lastWithdrawalSuccess String No The last withdrawal success.
registrationDate String No The registration date.
expiryDate String No The expiry date.
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, ccExpMonth, ccExpYear, ccNameOnCard, ccToken, brand, uniqueCC, bin, last4Digits, billingAddress, timeStamp, merchantSecretKey.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "69",
    "clientRequestId": "110",
    "userPaymentOptionId": "741",
    "ccToken":"ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0A
    TwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA==",
    "brand": "visa",
    "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=", 
    "bin": "411111",
    "last4Digits": "1111",
    "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.
userPaymentOptionId Long On the fist 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.
ccToken String A hashed value of the credit card number.
brand String The brand of the credit card, i.e. Visa, MasterCard, 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.
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.

addUPOCreditCardByTempToken

This method adds a credit card temporary 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 temporary token in the response that represents the consumer’s credit card. The next time the consumer completes a transaction, the merchant sends SafeCharge the temporary token instead of the consumer’s credit card information. The temporary token value represents the consumer’s credit card number.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/addUPOCreditCardByTempToken.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCardByTempToken.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/addUPOCreditCardByTempToken.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "sessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "487106",
    "clientRequestId": "110",
    "ccTempToken":"ZQBxAEgAawBpAHEAcwBkACQAcAB2AGcAcQAlAFkAYQBcACwAdQBHAD0ATwB4AE8AKwA4AE8ALQA9ACMAZABsADgAeAArAEcAdwAvAGkAQAAzAA==",
    "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":""
    },
    "timeStamp": "20150915161438",
    "checksum": "f84c4e7e7d5aa1e83cd785100746bafc"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOCreditCardByTempToken.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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 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.
ccTempToken String Yes A hashed value of the credit card number.
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 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

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "SessionToken":"9610a8f6-44cf-4c4f-976a-005da69a2a3b",
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "69",
    "useTokenId":"",
    "clientRequestId": "110", 
    "userPaymentOptionId": "741",
    "status": " SUCCESS ", 
    "errCode": "0",
    "reason": "",
    "version": "1"
}
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.
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.
userPaymentOptionId Long 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.
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.

addUPOAPM

This method adds an APM UPO account for specific users according to their User Token ID. Once an APM UPO is added to a consumer’s UPO list, the APM is displayed in the user’s available payment options on the payment page.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/addUPOAPM.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/addUPOAPM.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/addUPOAPM.do
Example Request
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": "8263015379487437770",
    "merchantSiteId": "39", 
    "userTokenId": "testUserToken",
    "clientRequestId": "43", 
    "paymentMethodName": "apmgw_expresscheckout", 
    "apmData": {
        "email": "user@mail.com"
    },
    "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": "20150915153043",
    "checksum": "836b57c4737099e89bbe9caed83a902e"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/addUPOAPM.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
paymentMethodName 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.
apmData Map Yes List of name-value pairs that contain the parameters of the user payment option. For more information, refer to APM Account Identifiers.
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, paymentMethodName, apmData.XXX (for apmData.XXX need to list all depend in the current APM account fields, in the exact same order they were sent in apmData class), billingAddress, timeStamp, merchantSecretKey.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "56",
    "clientRequestId": "43", 
    "userPaymentOptionId": "742",
    "status": " SUCCESS ", 
    "errCode": "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 the merchant’s system.
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.
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.

editUPOCC

This method enables the editing of the modifiable credit card details for a specific user. The card number cannot be edited. To edit a credit card number, the UPO must be deleted and then added again.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/editUPOCC.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/editUPOCC.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/editUPOCC.do
Example Request
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": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken",
    "clientRequestId": "4556",
    "userPaymentOptionId": "741",
    "ccExpMonth": "12",
    "ccExpYear": "24", 
    "ccNameOnCard": "John Smith", 
    "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": "20150915155818",
    "checksum": "5d99ee468cd33c0b87d0dc2fc7585376"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/editUPOCC.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
userPaymentOptionId String Yes The unique user payment option ID as assigned by SafeCharge.
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; ccExpMonth and ccExpYear must be a date that is after the current 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, userPaymentOptionId, ccExpMonth, ccExpYear, ccNameOnCard, billingAddress, timeStamp, merchantSecretKey.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "62",
    "clientRequestId": "4556", 
    "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.
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.

editUPOAPM

This method enables the editing of the APM UPO account details for a specific user according to their User Token ID.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/editUPOAPM.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/editUPOAPM.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/editUPOAPM.do
Example Request
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": "8263015379487437770",
    "merchantSiteId": "39", 
    "userTokenId": "testUserToken", 
    "clientRequestId": "43",
    "userPaymentOptionId": "743", 
    "apmData": {
        "account_id": "userA@mail.com"
    },
    "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": "20150915160424",
    "checksum": "71b589416aba502be1521e1ce6b94726"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/editUPOAPM.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
userPaymentOptionId String Yes The unique user payment option ID as assigned by SafeCharge.
apmData Map Yes List of name-value pairs that contain the parameters of the user payment option. For more information, refer to APM Account Identifiers.
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, userPaymentOptionId, apmData.XXX (for apmData.XXX need to list all depend in the current APM account fields, in the exact same order they were sent in apmData class), billingAddress, timeStamp, merchantSecretKey.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "65",
    "clientRequestId": "43", 
    "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.
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.

deleteUPO

This method deletes a UPO for a specific user from their list of registered UPOs. Once a UPO is deleted, it is no longer displayed on the user’s payment page. A deleted UPO may be added through any of the addUPO calls.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/deleteUPO.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/deleteUPO.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/deleteUPO.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "testUserToken", 
    "clientRequestId": "108", 
    "userPaymentOptionId": "742",
    "timeStamp": "20150915151243",
    "checksum": "c2f1ccf85719ba0a69022c7753e9ba9b"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/deleteUPO.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
userPaymentOptionId String Yes The unique user payment option ID as assigned by SafeCharge.
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, userPaymentOptionId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "60",
    "clientRequestId": "108", 
    "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.
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.

getUserUPOs

This method returns the registered payment options for a specific user according to their User Token ID.

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/getUserUPOs.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/getUserUPOs.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/getUserUPOs.do
Example Request
1
2
3
4
5
6
7
8
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39", 
    "userTokenId": "testUserToken", 
    "clientRequestId": "107",
    "timeStamp": "20150915151231",
    "checksum": "aa7566ab686602fe38a62d40d796bb01"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/getUserUPOs.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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

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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "58",
    "clientRequestId": "107", 
    "status":"SUCCESS", 
    "errCode": "0",
    "reason" : "",
    "version": "1", 
    "paymentMethods": [ {
        "userPaymentOptionId": "741",
        "paymentMethodName":"cc_card",
        "upoName":"Credit Card",
        "upoRegistrationDate":"",
        "upoStatus": "enabled",
        "expiryDate": "",
        "billingAddress":{
            "firstName": "some first name",
            "lastName": "some last name",
            "phone": "972502457558",
            "address": "some street",
            "zip": "",
            "city": "some city",
            "countryCode": "GB",
            "state": "",
            "email": "someemail@somedomain.com",
            "county":""
        },
        "upoData": {
            "cardType": "",
            "ccCardNumber": "4****1111", 
            "ccCardNumberHash":"68bfb396f35af3876fc509665b3dc23a0930aab1",
            "ccExpMonth": "12",
            "ccExpYear": "24",
            "ccNameOnCard": "John Smith",
            "ccToken" :"",
            "brand": "visa",
            "uniqueCC": "aL+zlvNa84dvxQlmWz3COgkwqrE=", 
            "bin": "411111",
            "last4Digits": ""
            }
        },
        {
        "userPaymentOptionId": "742",
        "paymentMethodName":"apmgw_expresscheckout",
        "upoName": "Paypal",
        "upoRegistrationDate":"",
        "upoStatus ": "suspended",
        "expiryDate": "",
        "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":""
        },
        "upoData": {
            "account_id": "user@mail.com"
            }
        }]
}
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.
paymentMethods Class List of Payment Options (See Below).

List of Payment Options:

PARAMETER DESCRIPTION
userPaymentOptionId The unique user payment option ID as assigned by SafeCharge.
paymentMethodName The unique name of the payment method (for example apmgw_Neteller). For a list of possible values, see APM Unique SafeCharge Names.
upoName User friendly name that helps identify the account.
upoRegistrationDate The date that the UPO was registered in the following format: YYYYMMDDHHmmss
upoStatus The status of the UPO for the user. Possible values are: suspended and enabled.
expiryDate Indicates whether or not the UPO has expired.
billingAddress firstName,
lastName,
address,
phone,
zip,
city,
countryCode(two-letter ISO country code),
state(two-letter ISO state code),
email,
county
upoData This block contains the UPO details of the user.

Please refer to APM Account Identifiers for more information.

Please note: Only the relevant parameters for a specific UPO are returned when they are stored in SafeCharge’s system.



APM Unique SafeCharge Names

The following table provides a list of payment method names that can be sent through the paymentMethodName and paymentMethod parameters.

PAYMENT METHOD NAME DESCRIPTION
cc_card Credit Card
dc_card Debit Card
ABAQOOS ABAQOOS
ACC Moneybookers Credit/Debit card
AGMO AGMO
ALIPAY Alipay
alphaclick_do alphaclick_do
apmgw_2C2P_APMs 2C2P APMs
apmgw_2C2P_BAY_ATM 2C2P_BAY_ATM
apmgw_2C2P_BAY_BANKCOUNTER 2C2P_BAY_BANKCOUNTER
apmgw_2C2P_BAY_IBANKING 2C2P_BAY_IBANKING
apmgw_2C2P_BAY_WEBPAY 2C2P_BAY_WEBPAY
apmgw_2C2P_BBL_ATM 2C2P_BBL_ATM
apmgw_2C2P_BBL_BANKCOUNTER 2C2P_BBL_BANKCOUNTER
apmgw_2C2P_BBL_IBANKING 2C2P_BBL_IBANKING
apmgw_2C2P_BICG_OVERTHECOUNTER 2C2P_BICG_COUNTER
apmgw_2C2P_CreditCards 2C2P CreditCards
apmgw_2C2P_KBANK_ATM 2C2P_KBANK_ATM
apmgw_2C2P_KBANK_BANKCOUNTER 2C2P_KBANK_COUNTER
apmgw_2C2P_KBANK_IBANKING 2C2P_KBANK_IBANKING
apmgw_2C2P_KTB_ATM 2C2P_KTB_ATM
apmgw_2C2P_KTB_BANKCOUNTER 2C2P_KTB_BANKCOUNTER
apmgw_2C2P_KTB_IBANKING 2C2P_KTB_IBANKING
apmgw_2C2P_KTB_WEBPAY 2C2P_KTB_WEBPAY
apmgw_2C2P_MPAY_OVERTHECOUNTER 2C2P_MPAY_COUNTER
apmgw_2C2P_PAYATPOST_OVERTHECOUNTER 2C2P_PAYPOST_COUNTER
apmgw_2C2P_SCB_ATM 2C2P_SCB_ATM
apmgw_2C2P_SCB_BANKCOUNTER 2C2P_SCB_BANKCOUNTER
apmgw_2C2P_SCB_IBANKING 2C2P_SCB_IBANKING
apmgw_2C2P_SCB_WEBPAY 2C2P_SCB_WEBPAY
apmgw_2C2P_TBANK_ATM 2C2P_TBANK_ATM
apmgw_2C2P_TBANK_BANKCOUNTER 2C2P_TBANK_COUNTER
apmgw_2C2P_TBANK_IBANKING 2C2P_TBANK_IBANKING
apmgw_2C2P_TESCO_OVERTHECOUNTER 2C2P_TESCO_COUNTER
apmgw_2C2P_TMB_ATM 2C2P_TMB_ATM
apmgw_2C2P_TMB_BANKCOUNTER 2C2P_TMB_BANKCOUNTER
apmgw_2C2P_TMB_IBANKING 2C2P_TMB_IBANKING
apmgw_2C2P_TMB_WEBPAY 2C2P_TMB_WEBPAY
apmgw_2C2P_TOT_OVERTHECOUNTER 2C2P_TOT_COUNTER
apmgw_2C2P_TRUEMONEY_OVERTHECOUNTER 2C2P_TRUEMON_COUNTER
apmgw_2C2P_UOB_ATM 2C2P_UOB_ATM
apmgw_2C2P_UOB_BANKCOUNTER 2C2P_UOB_BANKCOUNTER
apmgw_2C2P_UOB_IBANKING 2C2P_UOB_IBANKING
apmgw_2C2P_UOB_WEBPAY 2C2P_UOB_WEBPAY
apmgw_ABAQOOS ABAQOOS
apmgw_Alfa_Click Alfa-Click
apmgw_Alipay Alipay
apmgw_AstroPay AstroPay
apmgw_Astropay_TEF Astropay TEF
apmgw_Astropaycard_PPRO Astropaycard-PPRO
apmgw_AstropayBankPayouts AstropayBankPayouts
apmgw_Banco_do_Brasil Banco do Brasil
apmgw_BancoSantander BancoSantander
apmgw_Bitpay Bitpay
apmgw_BKM_Ekspress BKM Ekspress
apmgw_Boku Boku
apmgw_BOLETO BOLETO
apmgw_Boleto_Bancario_PPRO Boleto Bancario-PPRO
apmgw_Bpay Bpay
apmgw_Bradesco Bradesco
apmgw_cashU cashU
apmgw_Ceska_Sporitelna Ceska_Sporitelna
apmgw_Citadel Citadel
apmgw_ClickandBuy ClickandBuy
apmgw_CSOB CSOB
apmgw_CSOB_Bank CSOB_Bank
apmgw_CSOB_SK CSOB_SK
apmgw_Davivienda Davivienda
apmgw_DineroMail DineroMail
apmgw_Dotpay Dotpay
apmgw_E_Pro E-Pro
apmgw_EasyEFT EasyEFT
apmgw_ecoPayz ecoPayz
apmgw_eKonto eKonto
apmgw_ELV ELV
apmgw_EnterCash EnterCash
apmgw_Epay_bg Epay.bg
apmgw_EpayLink EpayLink
apmgw_Epin Epin
apmgw_EPS EPS
apmgw_ERA ERA
apmgw_Euteller Euteller
apmgw_Ewire Ewire
apmgw_expresscheckout PayPal
apmgw_Fast_Bank_Transfer Fast Bank Transfer
apmgw_Faster_Bank_Transfer Faster_Bank_Transfer
apmgw_FIO_Banka FIO_Banka
apmgw_FORTUNA_CREDIT_CARD FORTUNA_CREDIT_CARD
apmgw_FORTUNA_OFFLINE_BANKS FORTUNA_OFFLINE_BANKS
apmgw_FundSend FundSend
apmgw_Giropay Giropay
apmgw_GoPay GoPay
apmgw_HALCASH HALCASH
apmgw_HiPay HiPay
apmgw_IBAN_on_demand IBAN on demand
apmgw_Ibanq Ibanq
apmgw_iDeal iDeal
apmgw_iDebit iDebit
apmgw_IDS IDS
apmgw_Infin Infin
apmgw_Ininal Ininal
apmgw_Inpay Inpay
apmgw_InstaDebit InstaDebit
apmgw_InstantTransfer InstantTransfer
apmgw_Intercash_BD Intercash BD
apmgw_Intercash_BD_Express Intercash BD Express
apmgw_Intercash_prepaid Intercash prepaid
apmgw_iPara iPara
apmgw_ITAU ITAU
apmgw_KlarnaCheckout KlarnaCheckout
apmgw_KlarnaFixedPayments KlarnaFixedPayments
apmgw_KlarnaFlexiblePayments KlarnaFlexiblePayments
apmgw_KlarnaPayInX KlarnaPayInX
apmgw_Komercni_Banka Komercni_Banka
apmgw_Lobanet Lobanet
apmgw_mBank mBank
apmgw_MercadoPago MercadoPago
apmgw_micropayment micropayment
apmgw_MISTERCASH MISTERCASH
apmgw_Mobil_Odeme Mobil Odeme
apmgw_MOLpay MOLpay
apmgw_Moneta Moneta
apmgw_Moneta_Direct_Integration Moneta (Direct Integration)
apmgw_Moneta_Money_Bank Moneta Money Bank
apmgw_MoneyBookers MoneyBookers
apmgw_Mplatba Mplatba
apmgw_MULTIBANCO MULTIBANCO
apmgw_Neosurf Neosurf
apmgw_NeoSurf_Direct_Integration_ NeoSurf(Direct-Integration)
apmgw_Neteller Neteller
apmgw_NetellerGo NetellerGo
apmgw_OneCard OneCard
apmgw_OnShop OnShop
apmgw_OTP_Banka OTP_Banka
apmgw_Oxxo Oxxo
apmgw_P24 P24
apmgw_PagoFacil PagoFacil
apmgw_PaperCheque PaperCheque
apmgw_PaperChequeExpress PaperChequeExpress
apmgw_Pay_Com Pay.com Wallet
apmgw_PaySafeCard PaySafeCard
apmgw_Pingit Pingit
apmgw_PlusPay PlusPay
apmgw_POLI POLI
apmgw_POLINZ POLINZ
apmgw_PostePay PostePay
apmgw_Postova_Banka Postova_Banka
apmgw_Postovni_Sporitelna Postovni_Sporitelna
apmgw_Promsvyazbank Promsvyazbank
apmgw_PRZELEWY PRZELEWY
apmgw_PSE PSE
apmgw_Pugglepay Pugglepay
apmgw_QIWI QIWI
apmgw_Raberil Raberil
apmgw_Raiffeisenbank Raiffeisenbank
apmgw_Rapipago Rapipago
apmgw_Retail_Withdraw Retail Withdraw
apmgw_SafechargePM SafechargePM
apmgw_Safetypay Safetypay
apmgw_SafetypayPro SafetypayPro
apmgw_Santander Santander
apmgw_Sberbank Sberbank
apmgw_Sberbank_Slovensko Sberbank_Slovensko
apmgw_Sepa Sepa
apmgw_SEPA_Payouts SEPA Payouts
apmgw_Skrill_One_Tap Skrill One-Tap
apmgw_Slovenska_sporitelna Slovenska_sporitelna
apmgw_SMS_PIN SMS-PIN
apmgw_Sofort Sofort
apmgw_Sporopay Sporopay
apmgw_STPmex STPmex
apmgw_Suomen Suomen
apmgw_superCASH superCASH
apmgw_Supersonic_Ads Supersonic Ads
apmgw_Tatra_Banka Tatra_Banka
apmgw_Teb_atm Teb atm
apmgw_TELEINGRESO TELEINGRESO
apmgw_Ticket_Premium Ticket Premium
apmgw_Todito_Cash Todito Cash
apmgw_Todito_Cash_Direct_Integration_ Todito Cash(Direct Integration)
apmgw_Trustly Trustly
apmgw_Trustly_DI Trustly-DI
apmgw_Trustpay Trustpay
apmgw_UniCredit UniCredit
apmgw_Unicredit_Bank_SK Unicredit Bank_SK
apmgw_UnionPay UnionPay
apmgw_Univoucher Univoucher
apmgw_UseMyServices UseMyServices
apmgw_Vseobecna_uverova_Banka Vseobecna_uverova_Banka
apmgw_WeBanq WeBanq
apmgw_WebMoney WebMoney
apmgw_Webmoney_Direct_Integration_ Webmoney(Direct Integration)
apmgw_Webmoney_SMS_Invoice_ Webmoney(SMS+Invoice)
apmgw_Webpay Webpay
apmgw_WeChat WeChat
apmgw_Yandex_Money Yandex.Money
apmgw_YANDEXMONEY YANDEXMONEY
apmgw_ZBanc ZBanc
apmgw_Zimpler_PPRO Zimpler-PPRO
apmgw_Zong_SMS_PIN Zong SMS-PIN
ASTROPAYCARD AstroPay
Atlas Atlas SMS Payment
BALOTO Baloto
BANCOSANTANDER BancoSantander
BANKTRANSFER Fast Bank Transfer
BOLETO BOLETO
CASHU cashU
CHINAUNIONPAY-SSL UnionPay
Cielo Cielo
contact_do contact_do
dengiAtMail_ru_do dengiAtMail.ru_do
DID Moneybookers Direct Debit
DINEROMAIL DineroMail
directdebit_NL Direct Debit (NL)
directebanking Sofortuberweisung
EasyPay_do EasyPay_do
EBT Nordea Solo SE
EKONTO eKonto
elv Electronic Direct Debit (DE) / Lastschrift (ELV)
ENT eNETS
EPAY Epay.bg
EPS EPS
EPY ePay.bg
euroset_do euroset_do
EUTELLER Euteller
GIR Moneybookers Giropay
giro GIRO
GIROPAY Giropay
HALCASH HalCash
IDEAL iDeal
ideal IDEAL
IDL iDEAL
INSTADEBIT InstaDebit
ivr Phone Payment
ivrMobile Mobile phone
LiqPay_do LiqPay_do
LOBANET Lobanet
megafon_do megafon_do
MISTERCASH Mistercash
mobile_element_do mobile_element_do
MONETA Moneta
MoneXy_do MoneXy_do
Moneybookers Skrill
mts_do mts_do
MULTIBANCO MULTIBANCO
NEOSURF Neosurf
NETSWIPE Netswipe
NPY EPS
paydotcom Pay.com
Paykido Paykido-payment for kids
paypal PayPal
paypal_micropayment PayPal Micropayments
PAYSAFECARD PaySafeCard
PaySafeCard PaySafeCard
PLI POLi
POLI POLI
POLINZ POLINZ
ppp_AndroidPay Android Pay
ppp_ApplePay Apple Pay
ppp_BACSWithdraw BACS Withdraw
ppp_BankTransfer Bank Transfer
ppp_bPay bPay
ppp_Cheque Cheque
ppp_EasyEFTPayouts EasyEFT Payouts
PPP_NOP_DisplayInstructions PPP_NOP_DisplayInstructions
ppp_OfflineBanks Offline Banks
ppp_WesternUnion Western Union
ppp_WireTransfer Wire Transfer
premium_card Premium Card
PRZELEWY PRZELEWY
PWY Bank Transfer (Poland)
QIWIWALLET QIWI Wallet
QIWIWALLETUSD QIWI Wallet
rapida_do rapida_do
SAFETYPAY SafetyPay
SFT Moneybookers Sofortuberveisung
SID SID
sms Premium SMS
SMS_do SMS_do
SO2 Nordea Solo FI
SOFORT Sofort
TELEINGRESO TELEINGRESO
TODITOCARD ToditoCash
TRUSTPAY TrustPay
vias Adyen Card
WEBMONEY WebMoney
WLT Moneybookers Wallet



APM Account Identifiers

Some payment methods has their own requirements for identifying their end-users.
Through the apmData and userAccountDetails parameters, the merchant can provide SafeCharge with the relevant required parameters.
The following table provides a list of parameters required to be sent for the payment methods.

PAYMENT METHOD NAME DESCRIPTION ACCOUNT IDENTIFIER PARAMETER NAME
cc_card Credit Card bin,
brand,
cardType,
ccCardNumber,
ccCardNumberHash,
ccExpMonth,
ccExpYear,
ccNameOnCard,
ccToken,
ccTokenId,
isPrepaidCard,
uniqueCC
dc_card Debit Card bin,
brand,
cardTypeb,
ccCardNumber,
ccCardNumberHash,
ccExpMonthb,
ccExpYearb,
ccNameOnCard,
ccToken,
ccTokenId,
isPrepaidCard,
uniqueCC
apmgw_2C2P_CreditCards CreditCards accountId,
cardUniqueId,
maskedPan
apmgw_ABAQOOS ABAQOOS account_id
apmgw_Ceska_Sporitelna Ceska_Sporitelna account_id,
bankaddress,
bankcityb,
bankname,
banknumber,
bankpostalcode,
bankstreet
apmgw_Citadel Citadel citadel_account_numberAU,
citadel_account_numberCA,
citadel_bank_city,
citadel_bank_codeCA,
citadel_bank_name,
citadel_branch_codeAU,
citadel_branch_codeCA,
citadel_holder_name,
citadel_holder_name,
citadel_ibanMX,
citadel_swift_code
apmgw_ecoPayz ecoPayz account_id
apmgw_EnterCash EnterCash entercach_account_id,
entercach_bank_account_number,
entercach_bank_clearing_number,
entercach_bic,
entercach_iban,
entercash_beneficiaryName
apmgw_Ewire Ewire account_id
apmgw_expresscheckout PayPal account_id,
email,
paypalDirectFlow,
referenceID,
subMethod

For PayPal (redirect): no account fields required. For PayPal (direct): send the value “ReferenceTransaction” in Sub_Method field, and also send the numeric value the merchant received in reference_Id field.
apmgw_Fast_Bank_Transfer Fast Bank Transfer accountType,
additionalInfo1,
additionalInfo2,
additionalInfo3,
addressLine1,
addressLine2,
addressLine3,
bankAccountNumber,
bankCode,
bankCountry,
bankName,
branchAddress,
branchCode,
checkDigits,
city,
countryOfBirth,
dateOfBirth,
iban,
payee,
payeeCountry,
placeOfBirth,
postCode,
state,
swift,
title

Note that some parameters are mandatory per country. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com
apmgw_Faster_Bank_Transfer Faster_Bank_Transfer accountType,
additionalInfo1,
additionalInfo2,
additionalInfo3,
addressLine1,
addressLine2,
addressLine3,
bankAccountNumber,
bankCode,
bankCountry,
bankName,
branchAddress,
branchCode,
checkDigits,
city,
countryOfBirth,
dateOfBirth,
iban,
payee,
payeeCountry,
placeOfBirth,
postCode,
state,
swift,
title

Note that some parameters are mandatory per country. For more information, please contact SafeCharge’s Integration Team at integration@safecharge.com
apmgw_FIO_Banka FIO_Banka account_id,
bankaddress,
bankcity,
bankname,
banknumber,
bankpostalcode,
bankstreet
apmgw_iDebit iDebit iDebit_account_id
apmgw_IDS IDS ids_account_id
apmgw_InstaDebit InstaDebit account_id
apmgw_Intercash_BD Intercash BD account_id
apmgw_Intercash_BD_Express Intercash BD Express account_id
apmgw_KlarnaCheckout KlarnaCheckout APMBirthDate,
Billing_Address,
Gender,
PersonalId,
Shipping_Address
apmgw_KlarnaFixedPayments KlarnaFixedPayments APMBirthDate,
Billing_Address,
Gender,
PersonalId,
Shipping_Address
apmgw_KlarnaFlexiblePayments KlarnaFlexiblePayments APMBirthDate,
Billing_Address,
Gender,
PersonalId,
Shipping_Address
apmgw_KlarnaPayInX KlarnaPayInX APMBirthDate,
Billing_Address,
Gender,
PersonalId,
Shipping_Address
apmgw_Komercni_Banka Komercni_Banka account_id,
bankaddress,
bankcity,
bankname,
banknumber,
bankpostalcode,
bankstreet
apmgw_mBank mBank account_id,
bankaddress,
bankcity,
bankname,
banknumber,
bankpostalcode,
bankstreet
apmgw_Moneta Moneta account_id
apmgw_Moneta_Direct_Integration Moneta (Direct Integration) moneta_account_id,
moneta_payment_password
apmgw_Moneta_Money_Bank Moneta Money Bank account_name,
account_number,
AccountID,
bank_code,
prefix
apmgw_MoneyBookers MoneyBookers account_id
apmgw_Neteller Neteller nettelerAccount,
nettelerSecureId
apmgw_PaperCheque PaperCheque account_id
apmgw_PaperChequeExpress PaperChequeExpress account_id
apmgw_PaySafeCard PaySafeCard account_id,
wd_pay_safe_birthdate,
wd_pay_safe_first_name,
wd_pay_safe_last_name
apmgw_Pingit Pingit pingit_phone_number
apmgw_Pugglepay Pugglepay pugglepay_account_id
apmgw_QIWI QIWI qiwi_phonenumber
apmgw_Raiffeisenbank Raiffeisenbank account_id,
bankaddress,
bankcity,
bankname,
banknumber,
bankpostalcode,
bankstreet
apmgw_Sberbank Sberbank account_name,
account_number,
AccountID,
bank_code,
prefix
apmgw_Sepa Sepa bic,
iban,
verification_email
apmgw_Skrill_One_Tap Skrill One-Tap account_id,
recurring_id
apmgw_STPmex STPmex account_id
apmgw_Ticket_Premium Ticket Premium account_id
apmgw_Trustly_DI Trustly-DI account_id,
bank,
clearinghouse,
iban_last_digits
apmgw_Unicredit_Bank_SK Unicredit Bank_SK account_name,
account_number,
AccountID,
bank_code,
prefix
apmgw_WeBanq WeBanq account_id
apmgw_WebMoney WebMoney Account_id
apmgw_Webmoney_Direct_Integration_ Webmoney(Direct Integration) wd_web_money_direct_account_id
apmgw_Webmoney_SMS_Invoice_ Webmoney(SMS+Invoice) webmoney_account_id,
webmoney_purse_id
paydotcom Pay.com bin,
brand,
cardType,
ccCardNumber,
ccCardNumberHash,
ccExpMonth,
ccExpYear,
ccNameOnCard,
ccToken,
ccTokenId,
isPrepaidCard,
uniqueCC
ppp_BACSWithdraw BACS Withdraw bacs_withdraw_account_name,
bacs_withdraw_account_number,
bacs_withdraw_sort_code
ppp_EasyEFTPayouts EasyEFT Payouts easy_eft_payouts_account_number,
easy_eft_payouts_bank_name

suspendUPO

This method suspends a given payment option for a specific user. Once a UPO is suspended, the user can no longer process payments through that UPO. In the event that that the suspended payment method is a card, the user won’t be able to add it as UPO again as long as it is suspended. The merchant can reactivate suspended UPOs through the enableUPO method. The request should be sent to the following URL:

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/suspendUPO.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/suspendUPO.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/suspendUPO.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39", 
    "userTokenId": "testUserToken", 
    "clientRequestId": "109",
    "userPaymentOptionId": "743",
    "timeStamp": "20150915160842",
    "checksum": "a7b8817a0b761c11c756512366305595"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/suspendUPO.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
userPaymentOptionId String Yes The unique user payment option ID as assigned by SafeCharge.
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, userPaymentOptionId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "67",
    "clientRequestId": "109", 
    "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.
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.

enableUPO

This method enables a suspended payment option for a specific user, which enables the user to process transactions through that UPO. The request should be sent to the following URL:

@Links URL’s

@Live https://secure.safecharge.com/ppp/api/v1/enableUPO.do

@Test https://ppp-test.safecharge.com/ppp/api/v1/enableUPO.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/v1/enableUPO.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39", 
    "userTokenId": "testUserToken", 
    "clientRequestId": "135",
    "userPaymentOptionId": "743",
    "timeStamp": "20150915205412",
    "checksum": " 1c5343ba85154d4416855737d4e6888a"
}
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
jsonObject = JSON.stringify({
    // add input parameters in JSON format (provided in the 1st tab)
});

// prepare the POST header
var postheaders = {
    'Content-Type' : 'application/json',
    'Content-Length' : Buffer.byteLength(jsonObject, 'utf8')

};

// prepare the POST options
var optionspost = {
    host : 'ppp-test.safecharge.com', // the url
    port : 443, // the https port
    path : '/ppp/api/v1/enableUPO.do', // the methods endpoint 
    method : 'POST',
    headers : postheaders,
    body: jsonObject
};

// perform the POST call
var reqPost = https.request(optionspost, function(res) {

    res.on('data', function(response) {
        //process.stdout.write(response);
    });
});
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.
userPaymentOptionId String Yes The unique user payment option ID as assigned by SafeCharge.
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, userPaymentOptionId, timeStamp, merchantSecretKey.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "internalRequestId": "67",
    "clientRequestId": "109", 
    "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.
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.

Withdrawals

Withdrawal Overview

The Withdrawal process is the process of transferring funds from your account to the customer for winnings or refunds. Within a Withdrawal Request is a Withdrawal Order. A Withdrawal Request is your customer’s request to withdraw funds from their account and send those funds to their chosen payment method. A Withdrawal Order is part of a withdrawal request. An order includes the transaction and withdrawal details for funds to be withdrawn and sent to a single payment method.
When your customer issues a request to withdrawal funds a Withdrawal Request is generated with its own ID and status. If the customer requests that a withdrawal be split across several payment methods, one Withdrawal Request is generated and a Withdrawal Order for each unique payment method in which funds are to be sent. For the Withdrawal Request there is an ID and Status. For each Withdrawal Order part of the Withdrawal Request, there is a unique ID and status.

SafeCharge’s Withdrawal provides you with a platform that enables your customers to withdraw funds from their accounts to request refunds or winnings. These requests are made directly by the consumer and fulfilled by the merchant, as opposed to the CPanel where the requests are manually entered by the merchant the consumer’s request.
SafeCharge’s Withdrawal API provides you with a platform that enables your customers to withdraw funds from their accounts. The withdrawal may be in the form of a refund or winnings.
The messages your application sends to the Withdrawal API are called requests; the messages that SafeCharge returns are called responses. 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 your company’s application. It may be a consumer-facing application, such as a web site or online application.

API Services: This is SafeCharge’s web service that interacts with your application to synchronize and duplicate customer data such as payment methods between Gateways.

Withdrawal Flow

The Withdrawal process is the process of transferring funds from your account to the account of the customer for winnings or refunds.
The withdrawal process is divided into two phases:
1) In Phase 1, the customer specifies how much money they want to withdraw through the Withdrawal API and to which account they want to transfer the funds. The customer then submits the request and it is received by SafeCharge. This is called the Withdrawal Request Step.
2) In Phase 2, you process the transaction. If you are configured to receive DMNs (Direct Merchant Notifications), SafeCharge notifies you through a server-to-server DMN that a withdrawal request was received. You can reply to the DMN and approve or decline the request instantly. If you are not configured to receive DMNs, or you prefer to review the request manually, through the getRequests method you can then retrieve your pending requests and approve, cancel, decline, or split the requests. Splitting a request means transferring all or part of the customer’s funds across multiple accounts. That is called the Withdrawal Processing Step.


Single and Double Message Modes

When manually processing a request, you can process the withdrawal request in one of two modes, Single Message mode and Double Message mode. In Single Message mode, your administrator approves the transaction with the approveRequest method and the funds are settled and transferred to the customer’s account. In Double Message mode, your administrator approves the withdrawal request with the approveRequest method and the funds are only transferred when you settle the orders through the settleWithdrawalOrder method.
In both modes, Single and Double Message, the approveRequest is the same. Whether your transactions are processed in Single or Double Message mode is determined during your configuration. You cannot process transactions in both modes. To change which mode you process your transactions, contact SafeCharge Technical Support who can update your configuration.
The following diagram illustrates two steps of the withdrawal process.

The diagram below illustrates a merchant that redirects consumers to SafeCharge’s withdrawal page.



Withdrawalapiguidea

The diagram below illustrates a merchant’s flow where the customer requests the withdrawal from the merchant’s page.



Withdrawalapiguideb

  1. The customer chooses to withdraw funds from your site or application. You redirect your customers to the Withdrawal API through the withdraw.do URL, which populates it with the customer’s account details, withdrawal history requests, and relevant payment methods. For more information, see Redirection.
  2. The customer enters the withdrawal amount and selects the payment method account to withdraw to and clicks Submit on the Withdrawal API.
  3. (Optional) As the customer places the withdrawal request, if configured to receive DMNs, SafeCharge notifies you that a customer has initiated a withdrawal request. For more information on the DMN and how to handle it, see DMN Notification. If not configured for DMNs, you can use the Withdrawal API to retrieve your pending requests.
  4. (Optional) If configured for the DMN, you return a DMN Acknowledgment to SafeCharge indicating you received the DMN. In addition, your responses indicates how you want to process the transaction. If you want to review the transaction, you can postpone it or if you want to instantly process it, you can approve or decline the transaction.
  5. Your administrators review the withdrawal request and decide how the request should be processed. For more information regarding the processing of withdrawal requests, see Step 2: Withdrawal Processing.
  6. SafeCharge returns a response with the result of the request.
  7. In Double Message mode, you settle orders of requests that have been approved by you through the settleWithdrawalOrder method.

Withdrawal Integration

This section describes how you can integrate with the SafeCharge Withdrawal service in two steps:

Step 1:

Withdrawal Request
To process a withdrawal request, first you must redirect the customer to the Withdrawal API and handle the DMN or call the getRequests method to receive the customers’ requests.

Step 2:

Withdrawal Processing
After receiving all the information from the DMN or through the getRequests method, you can store the information and manage the withdrawal requests through your back office.
Through SafeCharge’s Withdrawal API, you can process your customer’s withdrawal request; you can perform the following actions:

Withdrawal Statuses

Each time you or your customer modifies the request or order, such as by canceling or approving the request, the Order Status and Request Status are updated in the CPanel and in the Withdrawal API.
There are four possible scenarios when a Request or Order status may be updated. The first scenario occurs when you issue an API call that affects the transaction, the updated status is returned in the response field wdRequestStatus and wdOrderStatus. The second possible scenario is when the action is initiated through the CPanel, the updated statuses are displayed in the Withdrawal report. The third scenario is when the issuer responds to the request. In this scenario, SafeCharge returns a DMN and updates the status in the Withdrawal report and Withdrawal API. The final scenario is when a customer initiates the change from within the Withdrawal API, for example, by canceling the request.

The table below lists each possible status of withdrawal requests and their definitions:

STATUS DESCRIPTION
Pending This status is returned when the initial request is placed before the transaction is processed.
In Process This status indicates that the request or order is being processed. This status is returned when an order of the request is approved, declined, or settled, but additional funds remain that may be withdrawn in a future request.
Partially Approved This status indicates that an order of the request has been settled and that the sum of the amounts in the settled orders is not equal to the request amount
Approved This status indicates the order or request have been settled and no additional funds are available to be withdrawn from the original deposit.
Canceled This status indicates that the customer initiated the termination of the request through the Withdrawal API.
Declined This status indicates that the merchant declined the request (through the withdrawal API or with a DMN response).



Redirection Integration

The Customer Withdrawal method redirects your customer from your site or application to the Withdrawal API. From the Withdrawal API, customers can initiate new withdrawal requests.
SafeCharge uses HTTPS requests in an automated mode to enable you to send transaction data to SafeCharge. SafeCharge uses these requests to process the transaction with the customer’s payment method and direct the customer to the Withdrawal API.
The HTTPS request includes the URL of the Withdrawal API and transaction parameters such as the amount of the transaction and the currency.

HTTPS requests must be in the following format:

https://(server_URL)?(Parameter1)=(Value1)&(Param2)=(Value2)…

FIELDS DESCRIPTION
(server_URL) This is the URL of the server and the command to accept incoming parameters. It is followed by a list of parameters and their values. There are two possible values for the server URL:
https://secure.safecharge.com/ppp/withdrawal/withdraw.do: Runs transactions in a live production environment.
https://ppp-test.safecharge.com/ppp/withdrawal/withdraw.do: Runs transactions in a test environment.
Note: This URL is only for testing purposes. Live transactions sent to this address will fail.
(Parameter) This is the name of the parameter as listed.
(Value) This is the value of the parameter. The ampersand (&) symbol separates sets of parameters and values.



Redirection Parameters

HTTPS requests to SafeCharge must contain certain parameters to be valid. The following list displays the mandatory and non-mandatory parameters that your website should send to SafeCharge to process a transaction.

Fields Mandatory Description
merchant_id Yes The merchant’s unique identification number provided by SafeCharge.
merchant_site_id Yes The merchant website’s unique identification number provided by SafeCharge.
user_token Yes This parameter indicates if the payment page required existing customers to register for the specific transaction.
When user_token=register, the payment page required the customer to register even if they are already registered in the system.
When user_token=auto, the payment page checked the database to determine if the customer was already registered.
merchantLocale No The language and country of the user in ISO code in the format language ISO_country ISO (e.g. en_US ).
wd_amount Yes A default withdrawal amount populated in the page.
wd_currency Yes The currency used in the transaction.
country No The two character ISO code that represents the customer’s country.
wd_min_amount Yes The minimum of the range of money that the customer can withdraw.
wd_max_amount Yes The maximum of the range of money that the customer can withdraw.
user_token_id Yes This parameter is a unique identifier for each end-user generated by the merchant.
userID No An external user Id you generate for the customer. This ID is for your records and tracking purposes only.
timeStamp Yes The GMT time when the transaction took place in the following format: YYYYMMDDHHMMSS
customSiteName No The merchant’s site name that should replace the default MerchantSite name. This parameter is useful for merchants operating many websites that are distinguished only by name.
customFieldX No Fifteen custom fields that you may use by replacing X with 1 to 15. The customFieldX that you have passed as the customFieldX parameter initially when making the first request to the Withdrawal API.
merchant_unique_id No The merchant’s unique ID.
This field is sent by the merchant and acts as a unique transaction reference identification.
version Yes The current version of the payment page. Currently, the version is 4.0.0. This value requires that all values of the HTTPS request are calculated as part of the checksum.
The values included in the checksum should be calculated in the order as they are displayed in each of your requests. If the order of the request does not match the order in which the parameters were calculated in the checksum, the request will fail.
checksum Yes The checksum of the request. This checksum should include all the parameters of the request and your Secret ID. For more information, see Calculating Request Checksums.

After redirecting your customer to the Withdrawal API, your customer enters their details, the amount of the withdrawal, and selects which payment methods the funds are withdrawn to.
The customer then clicks Submit on the Withdrawal API and SafeCharge sends you a DMN notification confirming that a withdrawal request was received or you retrieve the pending request through the getRequests method.

Calculating Request Checksums

To prevent errors that may be created while transferring HTTPS requests and for SafeCharge to authenticate HTTPS requests, you must create and include a SHA256 checksum into your request. The checksum is unique to each transaction as it is calculated according to specific details for each transaction such as the item amount and the time stamp of the transaction.
To generate checksums for each transaction, a SHA256 function must be integrated into your web application to allow the automatic calculation of the checksum when creating HTTPS POST requests.
There are two different methods for calculating request checksums, one for redirecting the customers to the Withdrawal API, and a second method for the API calls described in this guide (approveRequest, submitRequest etc.). In both scenarios, the checksum must be a string without spaces that is calculated from the values of all your parameters in the request.
If the checksum is not calculated as described, the request will fail.

To calculate a Withdrawal API or an API request checksum:

  1. Append all parameter values in the request in order as listed in this guide.
  2. Append your merchant secret key.
  3. Encrypt the results.

Calculating Request Checksums for the Withdrawal API

When redirecting customers to the payment page, the values included in the checksum should be calculated in the order as they are displayed in each of your requests.
For example:
- Merchant Secret Key
- merchant_id
- merchant_site_id
- user_token
- wd_currency
- wd_min_amount
- wd_max_amount
- user_token_id
- time_stamp
- fmIRGJ1nPKJqjjJuCSGesel4BVFRIJJn3J7XpUcWLdsGTOTYRVdkILedgG05nbHt479792380100514504231EUR1500ABC20140105160426

The checksum for this example is: 8e1e0d40d828d13d84ac01274d2ec53966efa056b36386bdae582015240f0a8e.
When initiating any of the calls listed in this guide, the values included in the checksum should be calculated in the order as they are displayed in the tables provides in this guide.
For example:
- approveRequest
- merchantId
- merchantSiteId
- wbRequestId
- merchantWDRequestId
- userAccountId
- operatorName
- comment
- timestamp
- Merchant Secret Key
- 84cb9e4dcc879663be2f30c62b497111.e9de3bada321d7ba8efa214688b5a125

DMN Notifications

Following events such as submitting a request, SafeCharge can send you server-to-server notifications known as Direct Merchant Notifications (DMN). DMNs include almost the same data as HTTPS GET or as HTTPS POST requests such as the transaction outcome, total amount, etc.; however, SafeCharge sends DMNs directly to your web server, ensuring reliable server-to-server communication between you and SafeCharge. DMNs can reduce the cases of data loss by establishing a direct two sided server-to-server connection, enabling SafeCharge to directly call back your web server.
You can instantly approve or reject withdrawal requests according to parameters you receive in the DMN by responding to the DMN with an Approve or Declined, or manually reviewing the request by responding to the DMN with Postpone. If you postpone, then you must, either via the API request or manually process the request and send SafeCharge the status through the approveRequest or declineRequest.

DMN Response Scenarios

SafeCharge can send DMNs following a variety of events as described in the table below. To configure which events you want SafeCharge to send a DMN, you must coordinate with the SafeCharge Integration team who configures your account.
In each Scenario there is one state and two statuses that may be changed during the processing of a Withdrawal request for both Single Message Mode (SMS) and Double Message Mode (DMS). The Request State indicates if the customer can issue further withdrawal requests from the transaction. Initially, the State is open; however, when a request is sealed or settled, the State is closed and no further withdrawal request can be made from the transaction.
The Request Status indicates the status of the request. The Request Status always begins in Pending. The Status can then be changed to Approved, Partially Approved for split transactions, cancelled for transactions cancelled by the user, and Declined for transactions you decline.
The Order Status indicates if the withdrawal request was settled. When this status is settled, the funds are sent to the customer.
The column Mode indicates what mode Single Message Mode (SMS) or Double Message Mode (DMS) your withdrawal service is configured for. You can change this mode by contacting the SafeCharge Integration team.
The following events can be configured to trigger a DMN:

Actions Available Options Mode Request State Request Status Order Status Description
Submit request Request Pending SMS/DMS Open Pending x SafeCharge sends a withdrawal request notification via the DMN once the customer submits a withdrawal request from within the Withdrawal API or API/CPanel.
Cancel request Request Canceled SMS/DMS Closed Canceled x SafeCharge sends a withdrawal request notification via the DMN once the customer cancels the request from within the Withdrawal API or API/CPanel.
Decline request Request Declined SMS/DMS Closed Declined x SafeCharge sends a withdrawal request notification via the DMN once the merchant declines the request through the API/CPanel or by returning “DECLINE” action to the “Submit request” DMN.
Approve request Request Approved SMS Closed Approved x SafeCharge sends a withdrawal request notification via the DMN once the merchant approves the request through the API/CPanel or by returning “APPROVE” action to the “Submit request” DMN. If the SMS and Gateway approve, the order status is updated to “Settled” and the request is approved.
Approve request Request Error SMS In Progress Error x SafeCharge sends a withdrawal request notification via the DMN once the request is approved through the API/CPanel or by returning “APPROVE” action to the “Submit request” DMN. If the SMS and Gateway decline the transaction, the order and request statuses are updated to “Error”.
Approve request Request Declined SMS Closed Declined x SafeCharge sends a withdrawal request notification via the DMN once the merchant approves the request through the API/CPanel or by returning “APPROVE” action to the “Submit request” DMN. If the SMS and Gateway decline the transaction, the order status is updated to “Error”. If auto seal is active and there are no pending orders, the request is declined.
Approve request Request In Progress SMS/DMS In Progress In Progress x SafeCharge sends a withdrawal request notification via the DMN when a request is approved through the API/CPanel or by returning “APPROVE” action to the “Submit request” DMN. If the SMS or DMS request is approved, the status is updated to “In Progress”.
Approve request Order Approved SMS/DMS In Progress In Progress Approved SafeCharge sends a withdrawal order notification via the DMN for created order upon merchant approving the request through API/CPanel or by returning “APPROVE” action to the “Submit request” DMN.
Approve request Order Settled SMS Closed Approved Settled SafeCharge sends a withdrawal order notification via the DMN when the request is approved through the API/CPanel or by returning “APPROVE” action to the “Submit request” DMN. If the SMS and Gateway approve, the order is settled.
Approve request Order Error SMS In Progress Error Error SafeCharge sends a withdrawal order notification via the DMN when a request is approved through API/CPanel or by returning “APPROVE” action to the “Submit request” DMN. If SMS and Gateway decline, the order status is updated to “Error”.
Seal request Request Partial SMS/DMS Closed Partial x SafeCharge sends a withdrawal request notification via the DMN when a request is sealed. If there are no orders left to be settled, at least one successfully settled order and settled amount less that the requested amount, the request status is updated to “Partial”.
Seal request Request Declined SMS/DMS Closed Declined x SafeCharge sends a withdrawal request notification via the DMN when a request is sealed. If there are no orders left to be settled and all other statuses are labeled as error or deleted, the request is declined.
Settle order Request Approved DMS Closed Approved x SafeCharge sends a withdrawal request notification via the DMN when an order is successfully settled.
Settle order Request Error DMS In Progress Error x SafeCharge sends a withdrawal request notification via the DMN when the Gateway declines the request and the status is updated to “Error”.
Settle order Request Partial DMS Closed Partial x SafeCharge sends a withdrawal request notification via the DMN when there are no orders left to be settled and at least one order is successfully settled and auto seal is active, but it the settled amount is less than the requested amount, the request status will be updated to “Partial”.
Settle order Request Declined DMS Closed Declined x SafeCharge sends a withdrawal request notification via the DMN once the merchant settles an order. If the Gateway declines, the order status is updated to “Error”. If auto seal is active and all other statuses are labeled as error or deleted, the request is declined.
Settle order Order Settled DMS In Progress/ Closed In Progress/ Approved/ Partial Settled SafeCharge sends a withdrawal order notification via the DMN when an order is successfully settled.
Settle order Order Error DMS In Progress/ Closed Error/ Declined/ Partial Error SafeCharge sends a withdrawal order notification via the DMN when the Gateway declines and the order status is updated to “Error”.
Place order Request Approved SMS Closed Approved x SafeCharge sends a withdrawal request notification via the DMN upon placing an order. If the SMS and Gateway approve and order amount is equal to the requested amount, the request is approved.
Place order Request Error SMS In Progress Error x SafeCharge sends a withdrawal request notification via the DMN upon placing an order. If the SMS and Gateway decline, the request statuses are updated to “Error".
Place order Request Partial SMS Closed Partial x SafeCharge sends a withdrawal request notification via the DMN upon placing an order in SMS. If auto seal is active, there are no other orders to be settled and settled amount < requested amount the request is updated to “Partial”.
Place order Request Declined SMS Closed Declined x SafeCharge sends a withdrawal request notification via the DMN upon placing an order. If the SMS and Gateway decline, the order status is updated to “Error”. If auto seal is active and all other statuses are “Delete” or “Error”, the request is declined.
Place order Request In Progress SMS/DMS In Progress In Progress x SafeCharge sends a withdrawal request notification via the DMN upon placing an order when the SMS/DMS request status is updated to “In Progress”.
Place order Order Approved SMS/DMS In Progress In Progress Approved SafeCharge sends a withdrawal order notification via the DMN upon placing an order.
Place order Order Settled SMS In Progress/ Closed In Progress/ Approved/ Partial Settled SafeCharge sends a withdrawal order notification via the DMN upon placing an order. If the SMS and GW approve, the order is settled.
Place order Order Error SMS In Progress Error Error SafeCharge sends a withdrawal order notification via the DMN upon placing an order. If the SMS and GW decline, the order status is updated to “Error”.
Place order Order settling externally DMS In Progress In Progress Settling externally SafeCharge sends a withdrawal order notification via the DMN upon placing an order in DMS and the order is eligible for external settlement.
Delete order Delete order DMS In Progress In Progress/ Error Deleted SafeCharge sends a withdrawal order notification via the DMN to delete the order.
Update order status externally Request Approved DMS Closed Approved x SafeCharge sends a withdrawal request notification via the DMN upon importing a file through the CPanel or API and once the order is settled successfully externally.
Update order status externally Request Error DMS In Progress Error x SafeCharge sends a DMN when an order’s status is updated externally to “Error”.
Update order status externally Request Partial DMS Closed Partial x SafeCharge sends a withdrawal request notification via the DMN upon importing a file through the CPanel or API and the order status is updated to “Settled externally”, which shows that it was successful. If auto seal is active and there are no other orders to be settled and the settled amount is less than the requested amount, the request is updated to “Partial”.
Update order status externally Request Declined DMS Closed Declined x SafeCharge sends a withdrawal request notification via the DMN upon importing a file through the CPanel or API and when an order’s status is updated to “Error”. If auto seal is active and all other orders are in deleted or listed as 'Error’ the request is declined.
Update order status externally Order Settled externally DMS In Progress/ Closed In Progress/ Approved/ Partial Settled externally SafeCharge sends a withdrawal order notification via the DMN when an order is settled successfully externally and updated to “Settle externally” through the CPanel or API.
Update order status externally Order Error DMS In Progress/ Closed Error/ Declined/ Partial Error SafeCharge sends a withdrawal order notification via the DMN when an order status is updated to “Error” through the CPanel or API.

DMN Response Parameters

The following table provides a list of parameters that may be returned in the DMN response:

Parameter Description Returned For?
wdOrderId ID of the withdrawal order generated by SafeCharge. Withdrawal Orders that are:
Approved
Pending
Settled
Error
wdRequestId ID of the withdrawal request generated by SafeCharge. All responses.
merchantWDRequestId ID of the withdrawal request generated by you. All responses when available.
merchantWDOrderId ID of the withdrawal order generated by you. Returned when available for Withdrawal orders that are:
Approved
Pending
Settled
Error
gwTrxId A transaction ID generated by SafeCharge’s Gateway for processing the transaction. Returned for Withdrawal orders that are:
Settled
Error
extTrxId An external transaction ID provided by the processor. Returned for Withdrawal orders when available that are:
Settled
Error
gwRelatedTransactionId The Gateway transaction ID of the transaction to be refunded. Returned for Withdrawal orders that are:
Settled
Error
notificationType The type of the DMN notification Request or Order All responses.
merchantSiteId Your site ID generated by SafeCharge. All responses.
merchantGwId Your Gateway ID generated by SafeCharge. Returned when available for Withdrawal orders that are:
Settled
Error
merchantLocale 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
Returned for requests and orders when submitted through the withdraw.do method.
wdRequestState The current state of the withdrawal request:
Open: The request is open. This is the initial state of all requests.
In Progress: This state indicates that the request was split and still open for additional withdraws. The request was not sealed.
Closed: The request is closed. No new operations can be performed on the request.
All responses.
wdRequestStatus The current status of the withdrawal request:
Pending: The initial Status of all requests. This indicates the transaction has not yet been processed.
Approved: The request was approved.
Declined: You or the APM declined the transaction.
Cancelled: The customer cancelled the request from the Withdraw page.
Partially Approved: The request is partially approved. This is relevant for split requests only.
Error: Indicates an error occurred.
All responses.
wdOrderStatus The current status of the withdrawal order:
Pending: The initial Status of all orders. This indicates the transaction has not yet been processed.
Approved: The order was approved.
Settling: The status when settleOrder is called.
SettlingPending: The status when the withdrawal order is being processed by the APM Gateway and the APM Gateway returns a ‘Pending’ status. This occurs when SafeCharge contacts the APM provider and is waiting for a final response.
Settled: The default Status of all requests. This status indicates the transaction has not yet been processed.
Deleted: The status of a withdrawal order that has been deleted.
Error: Indicates an error occurred.
Returned when available for Withdrawal orders that are:
Settled
Error
settlement Type The type of withdrawal:
Withdrawal
Refund
Returned for Withdrawal orders that are:
Approved
Pending
Settled
Error
gwErrCode Internal error code. Returned when available for Withdrawal orders that are:
Settled
Error
gwReason Error reason generated by the Gateway. Returned when available for Withdrawal orders that are:
Settled
Error
gwReasonCode Error code generated by the Gateway. Returned when available for Withdrawal orders that are:
Settled
Error
gwExtendedErrorCode Extended error code generated by the Gateway. Returned when available for Withdrawal orders that are:
Settled
Error
apmTrxId APM transaction ID. Returned when available for Withdrawal orders that are:
Settled
Error
apmReferenceId APM reference ID Can be used for reconciliation by the merchant when the payment is with APM
apmErrorDetails APM error details. Returned when available for Withdrawal orders that are:
Settled
Error
apmErrorCode APM error code. Returned when available for Withdrawal orders that are:
Settled
Error
firstName First name of the user. All responses when available.
lastName Last name of the user. All responses when available.
userTokenId This parameter is a unique identifier for each customer generated by the merchant. All responses.
zip Zip code of the customer. All responses when available.
city City of the customer. All responses when available.
country ISO country code of the customer. All responses when available.
state Customer’s state. All responses when available.
phone1 Customer’s telephone. All responses when available.
email Customer’s email address. All responses when available.
address Address of the customer. All responses when available.
amount Amount of the withdrawal request. All responses.
approvedAmount Approved amount of the withdrawal request. All responses.
currency ISO code of the currency of the request. All responses.
userId User ID you generate for the customer. All responses when available.
userPMId A unique ID automatically generated by SafeCharge that represents the payment method selected by the customer. All responses.
paymentMethod The type of payment method. All responses.
nameOnCard Name of the customer on the credit card. All responses for withdrawals to credit cards.
cardNumber Credit card number. All responses for withdrawals to credit cards.
Bin Bin number of the customer’s credit card. All responses when required by the payment method.
acquirerId Acquiring bank unique ID. The value 0 represents an invalid bank code. All responses when available.
expMonth Credit card expiration month. All responses for withdrawals to credit cards.
expYear Credit card expiration year. All responses for withdrawals to credit cards.
Version API version of the request. All responses.
pmDisplayName The user’s name as processed through an APM.
For credit card: last four digits of the card number (**********1111).
All responses.
userAccountId The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site. All responses when available.
operatorName Operator’s name either of the request or of the order, depending on the notification type. All responses when available.
customSiteName The merchant’s site name that should replace the default MerchantSite name. This parameter is useful for merchants operating many websites that are distinguished only by name. All responses when available.
customFieldx Fifteen custom fields that you may use by replacing X with 1 to 15. The customFieldX that you have passed as the customFieldX parameter initially when making the first request to the Withdrawal API. All responses when available.
Client_ip The customer’s IP address from where the withdrawal request was placed. All responses when available.
uniqueCC Unique identifier for credit card. All responses when available.
wdOrderAmount The amount of the order. All responses when available.
wdOrderCurrency The currency of the order. All responses when available.
responseTimeStamp Time set by SafeCharge, when the response is received from the Gateway in the format of YYYY-MM-DD.HH:MM:SS
For example: 2015-07-30.15:38:40
All responses.
ExternalaccountID Account ID for APMs. All responses when available.
externalAccountDescription Additional parameters that define the APM account in the following format:
[parameter name]: [parameter value]
[parameter name]: [parameter value]
Not including the account password
All responses when available.
feeAmount The amount of fee that was applied Sent in case a fee is applied
transactionAmount The real transaction amount (the request amount minus the fee amount) All responses when available.
merchantUniqueId This parameter is sent by the merchant and is used to associate a request with the merchant’s system All responses when available.
externalEmail Returned when the registered payment option has an e-mail as part of the user identification in the external payment provider, for example PayPal. All responses when available.
cardType The type of card used in the transaction. Possible values; ‘credit’ or ‘debit’. All responses.
upoRegistrationDate The date that the UPO was registered in the following format: YYYMMDDHHmmss All responses.
checksum The checksum of the request. This checksum should include all the parameters of the request and your Secret ID. For more information, see Calculating DMN Checksums. All responses.

DMN Acknowledgement Parameters

After receiving the DMN, you acknowledge that you received the DMN from SafeCharge. If SafeCharge does not receive a reply, SafeCharge continues to send DMNs every 15 minutes for the next 24 hours.
The table below provides a list of the parameters you must return to acknowledge that you received the DMN from SafeCharge for the initial withdrawal request:

PARAMETER MANDATORY DESCRIPTION
action Yes How you want SafeCharge to process the request: Approve, Decline, or Postpone.
message No The reason the action was taken.
errorCode No Error code from the merchant’s processing.
merchantUniqueId No Unique ID from the merchant’s system.

Calculating DMN Checksums

To authenticate SafeCharge’s DMNs, SafeCharge includes a checksum among the HTTPS parameters in the DMN. Use this checksum to verify that the DMN call-back was sent by SafeCharge. The checksum uses SHA256 encryption and is similar to the checksum you generated when sending HTTPS POST requests.

To calculate a DMN checksum:

  1. Concatenate all the parameter names and their values together in the exact order in which they are received in the DMN call-back.
    For example:
    wdRequestId=67655508&notificationType=WITHDRAW_REQUEST_NOTIFICATION&merchantSiteId=155555&merchantGwId=313102555555559767&merchantLocale=it_IT&wdRequestState=Closed&wdRequestStatus=Approved&firstName=JOHN+MIKE&lastName=DOE&userTokenId=2666666814012076&zip=23899&city=ROBBIATE&country=IT&phone1=%2B39377777708&email=test@gmail.com&address=VIA+MS.+JANE+ROE+n.null&amount=10.00&approvedAmount=10.00&currency=EUR&userPMId=96644448&paymentMethod=cc_card&nameOnCard=John+Mike=Doe&cardNumber=5*1111&bin=533322&acquirerId=master_card&expMonth=02&expYear=21&version=1.0&pmDisplayName=5*8184&uniqueCC=XBpCEaYLnKccS5tC2ebLfqsj8KQ%3D&responseTimeStamp=2017-07-04.16%3A14%3A02&feeAmount=0.0&transactionAmount=10.0&merchantUniqueId=UIOAPO4JSOWDFGU26Q00&upoRegistrationDate=20170627&checksum=3dad4f442bb0654e7502274f14b0e7cc

  2. Append your merchant secret key.

  3. Use SHA256 encryption on the result string of the concatenation to validate the checksum.

Withdrawal Processing Methods

After you receive the DMN notification that contains the transaction details of your customer’s withdrawal request, you can process the request. There are five ways in which you can handle a withdrawal request:

ACTION METHOD DESCRIPTION
Approve approveRequest The request is approved and the funds are withdrawn and sent to the customer’s chosen payment method.
Cancel cancelRequest The request is canceled and no funds are withdrawn.
Decline declineRequest The request is declined and no funds are withdrawn.
Split placeWithdrawalOrder The funds are split between several payment methods through multiple calls of this method. For partial withdrawal requests, the sealRequest method is also required.
Seal sealRequest When the amount of a withdrawal request to be returned to the customer is less than their original deposit, you can use this method to seal the deposit. Sealing a deposit means that in the Withdrawal API, the status of the deposit changes from “in process” to “partial” and no further withdrawals can be made from the request.

After placing a request, SafeCharge returns a response that describes the status of your request.

approveRequest

When your administrator approves a request, the customer’s funds are withdrawn to their payment method account.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/approveRequest.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/approveRequest.do



Input Parameters

Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/approveRequest.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": "100",
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "operatorName": "Admin",
    "comment": "some comment",
    "successUrl": "",
    "failUrl": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}
PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdRequestId Long Yes A unique ID generated by SafeCharge and returned in the initial DMN of the withdrawal request.
merchantWDRequestId String Yes
See Description
A unique ID which you generate for the withdrawal order.

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.
userAccountId String No The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName String No The name of administrator that approved the request.
comment String No The administrator’s comments regarding the transaction.
successUrl String No URLs used when processing with a redirect payment option. At this point, only Trustly is supported as a redirect payment option. Those URLs should be used when you wish to receive the result, upon which you will have the option to close the popup (if such is opened in the first place) once the end-user completes the process in the third-party payment provider’s page.
failUrl String No URLs used when processing with a redirect payment option. At this point, only Trustly is supported as a redirect payment option. Those URLs should be used when you wish to receive the result, upon which you will have the option to close the popup (if such is opened in the first place) once the end-user completes the process in the third-party payment provider’s page.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Output Parameters

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdOrderStaus": "Approved",
    "wdRequestId": "8675309",
    "wdOrderId": "8675309",
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306",
    "pmRedirectUrl": ""
}
PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when a withdrawal request is declined.
reason String Reason an error occurred.
wdRequestStatus String Status of withdrawal request.
Approved: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range. The status of the withdrawal request remains unchanged.
wdOrderStatus String Status of the withdrawal order.
Approved: Successful result in Single Message Mode.
Settled: Successful result in Double Message Mode.
Error: Unsuccessful result due to some technical failure, for example the order was sent with a parameter out of the allowed range.
wdRequestId Long ID of the withdrawal request generated by SafeCharge.
wdOrderId Long ID of the withdrawal order generated by SafeCharge.
merchantWDRequestId Integer A unique ID which you generate for the withdrawal request.
userAccountId String The customer’s Account ID on your site. Only you know this value and no validations are performed by SafeCharge.
pmRedirectUrl String If this parameter exists, you should redirect to the provided URL in order to complete the process with the third party payment provider.
This parameter is only relevant for payment methods that support withdrawals in redirect mode (such as Trustly).

cancelRequest

When your customer chooses to cancel a Pending request from within the Withdraw page, you send the input parameters to SafeCharge through the cancelRequest method. The status of the withdrawal is changed from Pending to Cancelled and no funds are transferred.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/cancelRequest.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/cancelRequest.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/cancelRequest.do
Example Request
1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "wdRequestId": "100",
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
userTokenId String Yes This parameter is a unique identifier for each customer generated by the merchant.
wdRequestId Long Yes A unique ID generated by SafeCharge returned in the DMN for the request.
merchantWDRequestId String Yes
See Description
A unique ID which you generate for the withdrawal order.

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.
userAccountId String No The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": "8675309",
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
wdRequestStatus String Status of withdrawal request:
Cancelled: The customer’s withdrawal request was cancelled.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range. The status of the withdrawal request remains unchanged.
wdRequestId Long A unique ID generated by SafeCharge for the withdrawal request.
merchantWDRequestId String A unique ID which you generate for the withdrawal request.
userAccountId String The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

declineRequest

When your administrator declines a request, the customer’s funds are not returned to their payment method.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/declineRequest.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/declineRequest.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/declineRequest.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "wdRequestId": "100",
    "merchantWDRequestId": "12345",
    "userAccountId": "8675309",
    "operatorName": "Admin",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdRequestId Long Yes A unique ID generated by SafeCharge returned in the DMN for the request.
merchantWDRequestId String Yes
See Description
A unique ID which you generate for the withdrawal order.

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.
userAccountId String No The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName String No The name of administrator that approved the request.
comment String No The administrator’s comments regarding the transaction.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": "8675309",
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
wdRequestStatus String Status of withdrawal request.
Declined: The withdrawal request was declined.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range. The status of the withdrawal request remains unchanged.
wdRequestId Long ID of the withdrawal request.
merchantWDRequestId Long A unique ID which you generate for the withdrawal request.
userAccountId String The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

placeWithdrawalOrder (Split Withdrawal)

When you want to split a withdrawal across several customer accounts, you must use the placeWithdrawalOrder method. This method creates an order for each account that funds are to be withdrawn to. Each order is processed individually and SafeCharge returns a status response for each order. You can continue to place withdrawal orders until the entire deposit has been withdrawn by the customer.
When your back-office user decides to return only part of the original deposit, the transaction appears as “in processing” on the Withdrawal API. If you want to allow customers to withdraw only a part of their deposit, and close the remaining amount in the Withdrawal API, you can seal the transaction. For more information, see the sealRequest method.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/placeWithdrawalOrder.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/placeWithdrawalOrder.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/placeWithdrawalOrder.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": "100",
    "merchantWDRequestId": "12345",
    "merchantOrderId": "12345",
    "userUniqueId": "8675309",
    "userPMId": "3846",
    "operatorName": "Admin",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdRequestId Long Yes Request ID that the withdrawal order will be related to.
merchantWDRequestId String Yes
See Description
A unique ID which you generate for the withdrawal request.

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.
merchantWDOrderId String No A unique ID which you generate for the withdrawal order.
merchantUniqueId String Yes
See Description
This parameter is sent by the merchant and is used to associate a request with 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.
userPMId Long Yes ID of the payment methods the customer wants the funds withdrawn to.
amount Double Yes Amount that the customer wants to withdraw.
currency String Yes ISO code of the currency of the request.
settlementType Enum Yes Describes the type of settlement, 0 indicates that the transaction is a withdrawal and 1 indicates that the transaction is a refund.
gwRelatedTransactionId Long Conditional Transaction ID of the request that the refund will be related to when the request is a refund request. Mandatory for refund requests.
userAccountId String No The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName String No The name of administrator that approved the request.
comment String No The administrator’s comments regarding the transaction.
successUrl String No URLs used when processing with a redirect payment option. At this point, only Trustly is supported as a redirect payment option. Those URLs should be used when you wish to receive the result, upon which you will have the option to close the popup (if such is opened in the first place) once the end-user completes the process in the third-party payment provider’s page.
failUrl String No URLs used when processing with a redirect payment option. At this point, only Trustly is supported as a redirect payment option. Those URLs should be used when you wish to receive the result, upon which you will have the option to close the popup (if such is opened in the first place) once the end-user completes the process in the third-party payment provider’s page.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdOrderStatus": "Approved",
    "wdRequestId": "8675309",
    "wdOrderId": "12345",
    "merchantWDRequestId": "741852",
    "merchantWDOrderId": "3846",
    "userAccountId": "5675306",
    "pmRedirectUrl": ""
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status Integer Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
wdRequestStatus String Status of withdrawal request.
Approved: Successful result.
In Progress: The request is pending.
Error: Unsuccessful result due to some technical failure, for example, the request was sent with a parameter out of the allowed range. The status of the withdrawal request remains unchanged.
wdOrderStatus String Status of the withdrawal order.
Approved: Successful result in Single Message Mode.
Settled: Successful result in Double Message Mode.
Error: Unsuccessful result due to some technical failure, for example, the order was sent with a parameter out of the allowed range.
wdRequestId Long ID of the withdrawal request generated by SafeCharge.
wdOrderId Long ID of the withdrawal order generated by SafeCharge.
merchantWDRequestId String A unique ID which you generate for the withdrawal request.
merchantWDOrderId String A unique ID which you generate for the withdrawal order.
userAccountId String The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
pmRedirectUrl String If this parameter exists, you should redirect to the provided URL in order to complete the process with the third party payment provider.

This parameter is only relevant for payment methods that support withdrawals in redirect mode (such as Trustly).

sealRequest

When the amount of a withdrawal request to be returned to the customer is less than their original deposit, you can use this method to seal the deposit. Sealing a deposit means that in the Withdrawal API, the status of the deposit changes from “in process” to “partial” and no further withdrawals can be made from the request.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/sealRequest.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/sealRequest.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/sealRequest.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestId": "100",
    "merchantWDRequestId": "12345",
    "userAccountId": "12345",
    "operatorName": "Admin",
    "comment": "Some comment.",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdRequestId Long Yes A unique ID generated by SafeCharge returned in the DMN for the request.
merchantWDRequestId String Yes
See Description
A unique ID which you generate for the withdrawal order.

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.
userAccountId String No The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
operatorName String No The name of administrator that approved the request.
comment String No The administrator’s comments regarding the transaction.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": "8675309",
    "merchantWDRequestId": "741852",
    "userAccountId": "5675306"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
wdRequestStatus Integer Status of withdrawal request.
Partially Approved: Successful result for the relevant order.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range. The status of the withdrawal request remains unchanged.
wdRequestId Long ID of the withdrawal request.
merchantWDRequestId String A unique ID which you generate for the withdrawal request.
userAccountId String The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

Withdrawal Requests Methods

submitRequest

If you want to submit a request without redirecting your customer to the Withdrawal API, for example, through your own application directly to SafeCharge, you can place the request through the submitRequest method.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/submitRequest.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/submitRequest.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/submitRequest.do
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "userId": "259",
    "userPMId": "3846",
    "userDetails":{
        "firstName": "John",
        "lastName": "Adams",
        "address": "XXXX",
        "phone": "XXXX",
        "zip": "XXXX",
        "city": "XXXX",
        "countryCode": "XXXX",
        "state": "XXXX",
        "email": "safecharge@safecharge.com"
    },
    "amount": "10.55",
    "currency": "GBP",
    "merchantWDRequestId": "12345",
    "merchantUniqueId": "12345",
    "userAccountId": "12345",
    "customSiteName": "Merchant's Site Name",
    "customFieldX": "1",
    "successUrl": "",
    "failUrl": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
userTokenId String Yes This parameter is a unique identifier for each customer generated by you.
userId String No User ID you generate for the customer.
userPMId Long Yes ID of the payment methods the customer wants the funds withdrawn to.
userDetails Class No firstName,
lastName,
address,
phone,
zip,
city,
countryCode,
state,
email
amount Double Yes Amount of the withdrawal order.
currency String Yes ISO code of the currency of the request.
merchantWDRequestId String Yes
See Description
A unique ID which you generate for the withdrawal order.

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.
merchantUniqueId String Yes
See Description
This parameter is sent by the merchant and is used to associate a request with 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.
userAccountId String No The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
customSiteName String No The merchant’s site name that should replace the default MerchantSite name. This parameter is useful for merchants operating many websites that are distinguished only by name.
customFieldX String No Fifteen custom fields that you may use by replacing X with 1 to 15. The customFieldX that you have passed as the customFieldX parameter initially when making the first request to the Withdrawal API.
successUrl String No URLs used when processing with a redirect payment option. At this point, only Trustly is supported as a redirect payment option. Those URLs should be used when you wish to receive the result, upon which you will have the option to close the popup (if such is opened in the first place) once the end-user completes the process in the third-party payment provider’s page.
failUrl String No URLs used when processing with a redirect payment option. At this point, only Trustly is supported as a redirect payment option. Those URLs should be used when you wish to receive the result, upon which you will have the option to close the popup (if such is opened in the first place) once the end-user completes the process in the third-party payment provider’s page.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdRequestId": "8675309",
    "merchantWDRequestId": "12345",
    "userId": "259",
    "userAccountId": "5675306",
    "pmRedirectUrl": ""
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status Integer Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
wdRequestStatus String Status of withdrawal request.
Approved: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range. The status of the withdrawal request remains unchanged.
wdRequestId Long ID of the withdrawal request generated by SafeCharge.
merchantWDRequestId Integer A unique ID which you generate for the withdrawal request.
userId String An external user Id you generate for the customer. This ID is for your records and tracking purposes only.
userAccountId String The customer’s Account ID on your site. Only you know this value and no validations are performed by SafeCharge.
pmRedirectUrl String If this parameter exists, you should redirect to the provided URL in order to complete the process with the third party payment provider.
This parameter is only relevant for payment methods that support withdrawals in redirect mode (such as Trustly).

getCandidatesForRefund

This method returns a list of a customer’s approved deposits that had not been refunded or were only partially refunded up to the last six months according to their userId. The list of refund requests returned by the getCandidatesForRefund method includes the transactionId for the withdrawal request, the paymentMethodID, the payment method’s name, and the customer’s account information.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/getCandidatesForRefund.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/getCandidatesForRefund.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/getCandidatesForRefund.do
Example Request
1
2
3
4
5
6
7
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdRequestId String Yes A unique ID generated by SafeCharge returned in the DMN for the request.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": ""
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.

Example Response

1
2
3
4
5
6
7
8
9
10
{
    "gwRelatedTransactionId": "8675309",
    "pmIssuer": "Visa",
    "pmName": "Credit Card",
    "pmDisplayName": "1111",
    "amount": "10.55",
    "remainingAmount": "1.55",
    "userPMId": "3846",
    "currency": "GBP"
}

TransactionsDetailList Block

PARAMETER DESCRIPTION
gwRelatedTransactionId TransactionMainId - ID of Gateway deposit transaction that can be refunded.
pmIssuer The credit card company that processed the original transaction.
pmName The name of the payment method, credit card, PayPal etc.
pmDisplayName For credit cards: Last 4 digits.
For Alternative Payment Methods: AccountID.
amount Amount of original deposit transaction.
remainingAmount Remaining amount of money from the original transaction that can be returned.
userPMId A unique ID automatically generated by SafeCharge that represents the payment method selected by the customer.
currency The currency used in the withdrawal.

getRequests

The getRequests method returns a list of a customer’s withdrawal requests.
In the request, you define the criteria that determine which requests are returned. For example, through the statusList parameter, you can request that SafeCharge only return Pending withdrawal requests.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/getRequests.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/getRequests.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/getRequests.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdRequestOrderCount": "",
    "userTokenId": "8675309",
    "userId": "259",
    "wdRequestId": "8675309",
    "merchantWDRequestId": "12345",
    "merchantUniqueId": "852",
    "dateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "statusList": "Approved",
    "stateList": "OPEN",
    "paymentMethodsList": "Credit Card",
    "countryIsoList": "GB",
    "amountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency":"GBP"
    },
    "userRegistrationDateRange": {
        "fromDate": "2014071000000",
        "toDate": "201407152359"
    },
    "sortField": "requestedAmount",
    "sortOrder": "ASC: Ascending",
    "firstResult": "0",
    "maxResults": "10",
    "operatorName": "",
    "wdRequestOrderCountRange": {
        "from" : "2",
        "to": "5"
    },
    "merchantSiteIds": ["1212", "1225", "1287"],
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdRequestOrderCount Integer No Retrieve only requests that have exactly number of orders. This parameter is overridden by the wdRequestOrderCountRange parameter (if it is present)
userTokenId String No This parameter is a unique identifier for each customer generated by you.
userId String No Your ID for the customer.
wdRequestId Long Yes A unique ID generated by SafeCharge returned in the DMN for the request.
merchantWDRequestId String Yes
See Description
A unique ID which you generate for the withdrawal order.

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.
merchantUniqueId String Yes
See Description
This parameter is sent by the merchant and is used to associate a request with 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.
dateRange String No Defines the date range of the requests you want to return.
statusList String No Defines the statuses of the requests you want to return.
The possible values include:
Approved,
Declined,
Pending,
In Progress,
Partially Approved,
Error
stateList String No Defines the state of the requests you want to return.
The possible values include:
OPEN,
IN_PROGRESS,
CLOSED
paymentMethodsList Array No Contains payment option IDs wrapped as a string.
countryIsoList Array No Contains an array of country ISO codes.
amountRange String No Returns a list of requests within the defined amount range.
userRegistrationDateRange String No Returns requests according to the date the customer registered.
sortField String No Defines how the response is to be sorted.
The permitted values include:
requestedAmount,
requestedCurrency,
approvedAmount,
requestStatus,
state,
creationDate,
lastModifiedDate,
displayStatus
sortOrder String No Defines how the sorted response is to be returned in descending or ascending order.
The permitted values include:
ASC: Ascending
DESC: Descending
firstResult Integer No You can define how many results are returned. The value of this parameter defines how many results are returned, for example, if you want to display only the first 10 records of the search result, then the firstResult should be 10.
If there is no firstResult, the default value is 0.
maxResults Integer No Based on the search result set of records, you can define how man results to return. The value of the maxResult parameter determines maximum number of requests to be returned, for example, if you want to display only the first 10 records of the search result, then the maxResult should be 10).
If there is no maxResult, all the results for defined by your request are returned.
operatorName String No The operatorName of the withdrawal requests
wdRequestOrderCountRange JSON object No Defines criteria for the count of orders – requests that have between “from” and “to” orders will be included in the response. This will return only requests that have 2 or more orders, but not more than 5 orders.
merchantSiteIds Array No Filter results by merchant site IDs. Only sites that belong to the merchant are allowed. For example:
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "merchantSiteName": "Any Site Name",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "withdrawalRequest": {
        "userTokenId": "",
        "userId": "",
        "userDetails": {
            "firstName": "John",
            "lastName": "Adams",
            "address": "XXXX",
            "phone": "XXXX",
            "zip": "XXXX",
            "city": "XXXX",
            "countryCode": "XXXX",
            "state": "XXXX",
            "email": "jamesd@safecharge.com"
        },
        "wdRequestId": "",
        "merchantWDRequestId": "",
        "userPMId": "",
        "approvedAmount": "",
        "merchantUniqueId": "",
        "requestedAmount": "",
        "requestedCurrency": "",
        "state": "",
        "wdRequestStatus": "",
        "wdRequestOrderCount": "",
        "pmName": "",
        "pmIssuer": "",
        "pmDisplayName": "",
        "creationDate": "",
        "lastModifiedDate": "",
        "dueDate": "",
        "WithdrawalOrders":{
            "wdOrderId": "12345",
            "merchantWDOrderId": "",
            "pmName": "",
            "pmIssuer": "",
            "pmDisplayName": "",
            "amount": "",
            "currency": "",
            "settlementType": "",
            "gwRelatedTransactionId": "",
            "wdOrderStatus": "",
            "gwTrxId": "",
            "errorCode  ": "",
            "extendedErrorCode": "",
            "reasonCode": "",
            "apmTrxId": "",
            "apmErrorDetails": "",
            "apmErrorCode": "",
            "operatorName": "",
            "comment": "",
            "creationDate": "",
            "lastModifiedDate": "",
            "userPMId": "",
            "numOfPMs": "",
            "netDepositAmount": "",
            "gwReason": "",
            "gwStatus": "",
            "merchantUniqueId": "",
            "executionTime": "",
            "userPMData": ""
        }
    },
    "totalCount": "1"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
merchantSiteName String The name of the site in your account where the request originated.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Approved: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
withdrawalRequest Class Details of the withdrawal orders and requests.
totalCount Integer Total number of requests returned.

Withdrawal Orders Methods

getOrders

The getOrders method returns a list of a customer’s withdrawal orders. In the request, you define the criteria that determine which orders are returned.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/getOrders.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/getOrders.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/getOrders.do
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "555",
    "userId": "6789",
    "wdOrderId": "12345",
    "wdRequestId": "8675309",
    "gwTrxId": "",
    "apmTrxId": "",
    "merchantWDOrderId": "",
    "merchantUniqueId": "",
    "dateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "statusList": [
        "Approved"
    ],
    "requestDateRange": {
        "fromDate": "2014071000000",
        "toDate": "201407152359"
    },
    "requestAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency":"GBP"
    },
    "orderAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency":"GBP"
    },
    "userRegistrationDateRange": {
        "fromDate": "2014071000000",
        "toDate": "201407152359"
    },
    "requestStatusList": [
        "Approved"
    ],
    "requestPaymentMethod": "",
    "NumOfPMsRange": [
        "fromNumOfPMs",
        "toNumOfPMs"
    ],
    "NetDepositRange": [
        "fromNetDeposit",
        "toNetDeposit"
    ],
    "countryIsoList" :[
        "DE"
    ],
    "sortField": "approvedAmount",
    "sortOrder": "ASC",
    "paymentMethodList": "cc_card",
    "firstResult": "0",
    "maxResults": "0",
    "operatorName": "Any Name",
    "wdRequestOrderCountRange ": {
        "from": "0",
        "to": "5"
    },
    "merchantSiteIds": ["1212", "1225", "1287"],
    "executionTimeRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
userTokenId String No This parameter is a unique identifier for each customer generated by you.
userId String No The user ID given by the merchant to the customer.
wdOrderId Long No A unique ID generated by SafeCharge returned in the DMN for the order.
wdRequestId Long No A unique ID generated by SafeCharge returned in the DMN for the request.
gwTrxId String No The ID of the order provided by SafeCharge’s Gateway.
apmTrxId String No The ID of the order provided by an APM.
merchantWDOrderId String No The order ID given by the merchant to the customer.
merchantUniqueId String Yes
See Description
This parameter is sent by the merchant and is used to associate a request with 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.
dateRange String No Defines the date range of the requests you want to return in. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
statusList String No Defines the statuses of the orders you want to return. Possible values include:
Approved,
Declined,
Pending,
In Progress,
Partially Approved,
Error
requestDateRange String No Defines the date range of the requests you want to return. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
requestAmountRange String No Returns a list of requests within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
orderAmountRange String No Returns a list of orders within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
userRegistrationDateRange String No Returns orders according to the date range the customer registered. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
requestStatusList Array No Defines the statuses of the orders you want to return. Possible values include:
Approved,
Declined,
Pending,
In Progress,
Partially Approved,
Error
requestPaymentMethod String No Contains payment option IDs wrapped as a string.
numOfPMsRange Array No The amount of the payment methods in range. This value consists of a “fromNumOfPMs” value and a “toNumOfPMs” value.
netDepositRange Array No The net deposit range.This value consists of a “fromNetDeposit” value and a “toNetDeposit” value.
countryIsoList Array No Contains an array of country ISO codes.
sortField String No Defines how the response is to be sorted.
Possible values include:
requestedAmount,
requestedCurrency,
approvedAmount,
requestStatus,
state,
orderCreationDate,
orderLastModifiedDate,
displayStatus,
orderAmount,
orderCurrency,
orderStatus,
requestCreationDate,
requestLastModifiedDate,
UserId,
firstName + lastName,
email,
numOfPM,
NetDepositAmount
sortOrder String No Defines how the sorted response is to be returned in descending or ascending order.
ASC: Ascending
DESC: Descending
paymentMethodsList String No Defines the type of payment method used in the order:
cc_card: credit card
dc_card: debit card.
firstResult Integer No You can define a start position in the list of results that are returned. The value of this parameter defines how many results to omit from the start of the result list, for example, if you want to omit the first 10 records of the search result, then the firstResult should be 10.
If there is no firstResult, the default value is 0.
maxResults Integer No Based on the search result set of records, you can define how many results to return. The value of the maxResult parameter determines maximum number of requests to be returned, for example, if you want to display only the first 10 records of the search result, then the maxResult should be 10).
If there is no maxResult, all the results for your request are returned.
operatorName String No The operatorName of the orders.
wdRequestOrderCountRange JSON object No Include only orders for withdrawal requests that contain “from” and “to” values representing the number of orders.
merchantSiteIds Array No Filtered results by merchant site IDs. Only sites that belong to the merchant are allowed.
executionTimeRange String No This defines the time range for execution. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
timeStamp String Yes The local time when the method call is performed in YYYYMMDDHHmm format.
checksum Hexadecimal string Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "merchantSiteName": "Any Site Name",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "orders": {
        "withdrawalOrder": "",
        "withdrawalRequest": ""
    },
    "totalCount": "10"

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
merchantSiteName String The name of the site in your account where the request originated.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
orders Class Details of the withdrawal orders and requests:
WithdrawalOrder
WithdrawalRequest
totalCount Integer Total number of requests returned.

settleWithdrawalOrder

When a customer submits a withdrawal request that includes several withdrawal orders and you want to settle specific withdrawal orders in the request, you can specify which order to settle through the settleWithdrawalOrder method. The settleWithdrawalOrder method settles a single order according the wdOrderID you send in the request. SafeCharge then processes the request and returns a response.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/settleWithdrawalOrder.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/settleWithdrawalOrder.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/settleWithdrawalOrder.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderId": "12345",
    "merchantWDOrderId": "12345",
    "userAccountId": "8675309",
    "triggerAutoSeal": "",
    "operatorName": "",
    "comments": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdOrderId Long Yes Request ID that the withdrawal order will be related to.
merchantWDOrderId String No A unique ID which you generate for the withdrawal order.
userAccountId String No The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.
triggerAutoSeal Boolean No A flag, which, if false, overrides the auto seal functionality.
operatorName String No The name of administrator that approved the request.
comments String No The administrator’s comments regarding the transaction.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal string Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdRequestStatus": "Approved",
    "wdOrderStatus": "Settled",
    "wdRequestId": "8675309",
    "wdOrderId": "12345",
    "merchantWDRequestId": "12345",
    "merchantWDOrderId": "12345",
    "userAccountId": "96385271"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API call.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
wdRequestStatus String Status of withdrawal request.
In Progress: Indicates that only part of the requested amount is approved and the request is not yet sealed. This status is returned only in Double Message Mode.
Approved: Successful result. This status is returned only in Double Message Mode. Partially Approved: An order as part of the request has been approved. Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range. The status of the withdrawal request remains unchanged.
wdOrderStatus String Status of the withdrawal order.
Settled: Successful result in Double Message Mode.
Error: Unsuccessful result due to some technical failure, for example the order was sent with a parameter out of the allowed range.
wdRequestId Long ID of the withdrawal request.
wdOrderId Long ID of the withdrawal order.
merchantWDRequestId String A unique ID which you generate for the withdrawal request.
merchantWDOrderId String A unique ID which you generate for the withdrawal order.
userAccountId String The customer’s Account ID on your site. The value of this parameters indicates which account balance the withdrawn funds should be applied to when your customer has multiple accounts on your site.

getOrderIds

The getOrderIds method returns a list your Order IDs per customer.
Through this method, you can retrieve the Order IDs and then settle those Orders through the settleOrderInBatch method.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/getOrderIds.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/getOrderIds.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/getOrderIds.do
Example Request
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
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "555",
    "userId": "6789",
    "wdOrderId": "12345",
    "wdRequestId": "8675309",
    "gwTrxId": "",
    "apmTrxId": "",
    "merchantWDOrderId": "",
    "merchantUniqueId": "",
    "dateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "merchantSiteIds": ["1212", "1225", "1287"],
    "executionTimeRange" : {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "statusList": [
        "Approved"
    ],
    "requestDateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "requestAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency":"GBP"
    },
    "orderAmountRange": {
        "fromAmount": "0",
        "toAmount": 1000,
        "Currency":"GBP"
    },
    "userRegistrationDateRange": {
        "fromDate": "201407100000",
        "toDate": "201407152359"
    },
    "requestStatusList": [
        "Approved"
    ],
    "requestPaymentMethod": "Some method",
    "NumOfPMsRange": {
        "fromNumOfPMs": "0",
        "toNumOfPMs": "2"
    },
    "NetDepositRange": {
        "fromNetDeposit": "200",
        "toNetDeposit": "500"
    },
    "countryIsoList": [
        "DE"
    ],
    "sortField": "requestedAmount",
    "sortOrder": "ASC",
    "paymentMethodsList": "cc_card",
    "firstResult": "0",
    "maxResults": "0",
    "operatorName": "Any Name",
    "wdRequestOrderCountRange": {
        "from" : "0",
        "to" : "5"
    },
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
userTokenId String No This parameter is a unique identifier for each customer generated by you.
userId String No The user ID given by the merchant to the customer.
wdOrderId Long No A unique ID generated by SafeCharge returned in the DMN for the order.
wdRequestId Long No A unique ID generated by SafeCharge returned in the DMN for the request.
gwTrxId String No The ID of the order provided by SafeCharge’s Gateway.
apmTrxId String No The ID of the order provided by an APM.
merchantWDOrderId String No The order ID given by the merchant to the customer.
merchantUniqueId String Yes
See Description
This parameter is sent by the merchant and is used to associate a request with 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.
dateRange String No Defines the date range of the requests you want to return in. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
merchantSiteIds Array No Filter results by merchant site IDs. Only sites that belong to the merchant are allowed.
executionTimeRange String No This defines the time range for execution of the transactions. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
statusList String No Defines the statuses of the orders you want to return. Possible values include:
Approved,
Declined,
Pending,
In Progress,
Partially Approved,
Error
requestDateRange String No Defines the date range of the requests you want to return. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
requestAmountRange String No Returns a list of requests within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
orderAmountRange String No Returns a list of orders within the defined amount range. This parameter consists of three values: “fromAmount”, “toAmount”, and “Currency”.
userRegistrationDateRange String No Returns orders according to the date range the customer registered. This value consists of a “fromDate” and a “toDate” in YYYYMMDDHHmm format.
requestStatusList Array No Defines the statuses of the orders you want to return. Possible values include:
Approved,
Declined,
Pending,
In Progress,
Partially Approved,
Error
requestPaymentMethod String No Contains payment option IDs wrapped as a string.
numOfPMsRange Array No The amount of the payment methods in range. This value consists of a “fromNumOfPMs” value and a “toNumOfPMs” value.
netDepositRange Array No The net deposit range.This value consists of a “fromNetDeposit” value and a “toNetDeposit” value.
countryIsoList Array No Contains an array of country ISO codes.
sortField String No Defines how the response is to be sorted. Possible values include:
requestedAmount,
requestedCurrency,
approvedAmount,
requestStatus,
state,
orderCreationDate,
orderLastModifiedDate,
displayStatus,
orderAmount,
orderCurrency,
orderStatus,
requestCreationDate,
requestLastModifiedDate,
UserId,
firstName + lastName,
email,
numOfPM,
NetDepositAmount
sortOrder String No Defines how the sorted response is to be returned in descending or ascending order.
ASC: Ascending
DESC: Descending
paymentMethodsList String No Defines the type of payment method used in the order. Possible values include:
cc_card: credit card
dc_card: debit card
firstResult Integer No You can define a start position in the list of results that are returned. The value of this parameter defines how many results to omit from the start of the result list, for example, if you want to omit the first 10 records of the search result, then the firstResult should be 10.
If there is no firstResult, the default value is 0.
maxResults Integer No Based on the search result set of records, you can define how many results to return. The value of the maxResult parameter determines maximum number of requests to be returned, for example, if you want to display only the first 10 records of the search result, then the maxResult should be 10).
If there is no maxResult, all the results for your request are returned.
operatorName String No The name of administrator that approved the request.
wdRequestOrderCountRange JSON Object No Include only orders for withdrawal requests that contain “from” and “to” values representing the number of orders.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "reason": "",
    "wdOrdersId": "",
    "totalCount": "10"

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the protocol.
status String Indicates if the API call was successful or not. Possible values include:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer The error code in the event of an error.
reason String Reason an error occurred.
wdOrderIds String List of Order IDs returned.
totalCount Integer Total number of orders returned according to the criteria you defined in the request.

settleOrdersInBatch

The settleOrdersInBatch method enables the merchant to settle a group of orders, as defined by the merchant, in one action. If you send any orders that have already been settled, SafeCharge ignores those orders and settles only those that are eligible to be settled.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/settleOrdersInBatch.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/settleOrdersInBatch.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/settleOrdersInBatch.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderId": "12345",
    "operatorName": "",
    "comment": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdOrderIds String Yes List of Order IDs returned.
operatorName String No The name of administrator that approved the request.
comment String No The administrator’s comments regarding the transaction.
timeStamp String Yes The local time when the method call is performed in the YYYYMMDDHHmmss format.
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "orders": "wdOrderId"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the protocol.
status String Indicates if the API call was successful or not.
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
orders String Details of the settleOrdersInBatch orders and requests. Possible values include:
wdOrderId,
operationStatus,
operationReason,
errorCode

deleteWithdrawalOrder

The deleteWithdrawalOrder method deletes and order for withdrawal made by the customer.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/deleteWithdrawalOrder.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/deleteWithdrawalOrder.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/deleteWithdrawalOrder.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
12
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderId": "12345",
    "merchantWDOrderId": "12345",
    "userAccountId": "8675309",
    "triggerAutoSeal": "",
    "operatorName": "",
    "comment": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdOrderId Long Yes ID of the withdrawal order to be deleted
merchantWDOrderId String No ID of the merchant’s withdrawal order.
userAccountId String No This is the end-user’s account ID on the side of the merchant. No validations are performed from the SafeCharge’s side.
triggerAutoSeal Boolean No A flag, which, if false, overrides the auto seal functionality.
operatorName String No Name of the operator deleting the order.
comment String No Operator’s comment for the operation.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "wdOrderId": "1234567890",
    "merchantWDOrderId": "12345",
    "userAccountId": "8675309"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the protocol.
status String Indicates if the API call was successful or not.
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
wdOrderId Long ID of the withdrawal order that is being deleted.
merchantWDOrderId String ID of the merchant’s withdrawal order.
userAccountId String This is an End User’s account ID on the side of the merchant. No validations are performed from SafeCharge’s side.

updateOrdersDetails

The updateOrdersDetails enables the update of the order’s details.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/updateOrdersDetails.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/updateOrdersDetails.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/updateOrdersDetails.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "wdOrderIds": "12345",
    "operatorName": "",
    "details": "",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
wdOrderIds String Yes ID of the withdrawal in SafeCharge’s system.
operatorName String No Name of the operator settling the order.
details String No Details of the execution time in YYYYMMDDHHmm format.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": "",
    "orders": "wdOrderId"
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the API.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.
orders String Details of the settleOrdersInBatch orders and requests. Possible values include:
wdOrderId,
operationStatus,
operationReason,
errorCode

Net Deposit methods

Net deposits are the sum of all the customer’s deposits minus any withdrawals across each of their payment methods per currency. This feature is optional.

getNetDeposits

The getNetDeposits method returns a list of a customer’s net deposits. After invoking the getNetDeposits method, you can manually update your customers’ net deposits to allow them to withdraw funds to payment methods in which the withdraw amount exceeds the deposit amount made for a particular payment method.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/getNetDeposits.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/getNetDeposits.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/getNetDeposits.do
Example Request
1
2
3
4
5
6
7
8
9
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "currency": "GBP",
    "userPMId": "12345",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
userTokenId String Yes This parameter is a unique identifier for each customer generated by you.
currency String Yes The currency of the net deposit.
userPMId Long Yes ID of the payment methods the customer wants the funds withdrawn to.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": ""
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the protocol.
status String Indicates if the API call was successful or not. The possible values are:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.

Example Response

1
2
3
4
5
6
7
8
{
    "amount": "10.55",
    "currency": "GBP",
    "userPMId": "3846",
    "pmDisplayName": "1111",
    "pmName": "Credit Card",
    "pmIssuer": "Visa"
}

netDeposits Block

PARAMETER TYPE DESCRIPTION
amount String The net deposit amount for the transaction.
currency String The currency of the net deposit.
userPMId String ID of the user’s payment method. This value is used when updating a net deposit amount through the UpdateNetDepositValue method.
pmDisplayName String For credit cards, the value is the last four digits of the card number (**********1111). Any other case an empty string is returned.
pmName String Type of the payment method: e.g. PayPal, Credit Card.
pmIssuer String Credit Card name (if cc_card or dc_card). If a credit card or debit card are not used, an empty string is returned.

UpdateNetDepositValue

The updateNetDepositValue enables you to update a customer’s net deposit.
Through this method, you can manually update your customers’ net deposits to allow them to withdraw funds to payment methods in which the withdraw amount exceeds the deposit amount made for a particular payment method.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/updateNetDepositValue.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/updateNetDepositValue.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/updateNetDepositValue.do
Example Request
1
2
3
4
5
6
7
8
9
10
11
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "userPMId": "12345",
    "amount": "10.55",
    "movementType": "4",
    "currency": "GBP",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
userTokenId String Yes This parameter is a unique identifier for each customer generated by the merchant.
userPMId Long Yes ID of the payment methods the customer wants the funds withdrawn to.
amount Double Yes The amount to be added to the net deposit amount. For example, $50.00 means $50 will be added to the net deposit in addition to the existing net deposit amount.
movementType Integer Yes The type of movement. Possible values are:
'1’ = Deposit
'2’= Manual Deposit
'3’ = Manual Withdrawal
'4’ = Withdrawal Order
currency String Yes The currency of the amount being applied to the net deposit.
timeStamp String Yes The local time when the method call is performed in the format: YYYYMMDDHHmmss
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": ""
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
version String The version of the protocol.
status String Indicates if the API call was successful or not. Possible values include:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.

getUserPaymentMethodNetDeposits

The getUserPaymentMethodNetDeposits enables the receipt of the net deposits per user payment method.



@Links URL’s

@Live https://secure.safecharge.com/ppp/api/withdrawal/getUserPaymentMethodNetDeposits.do

@Test https://ppp-test.safecharge.com/ppp/api/withdrawal/getUserPaymentMethodNetDeposits.do



Definition

https://ppp-test.safecharge.com/ppp/api/withdrawal/getUserPaymentMethodNetDeposits.do
Example Request
1
2
3
4
5
6
7
8
9
10
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userTokenId": "12345",
    "currency": "GBP",
    "country": "GB",
    "amount": "10.55",
    "timeStamp": "20150915143321",
    "checksum": "1cff28783432713e5dfc4fdc8f011b76"
}

Input Parameters

PARAMETER TYPE MANDATORY DESCRIPTION
merchantId Long Yes Your unique identification number provided by SafeCharge.
merchantSiteId Long Yes Your web site’s unique identification number provided by SafeCharge.
userTokenId String Yes This parameter is a unique identifier for each customer generated by you.
currency Double Yes ISO code of the currency of the request.
country String Yes ISO country code of the customer.
amount Double No The amount of the request withdrawal.
timeStamp String Yes The local time when the method call is performed in YYYYMMDDHHmmss format.
checksum Hexadecimal String Yes The checksum of the request. This checksum should be calculated to include every value of each parameter in the request and your Secret ID. For more information, see Calculating Request Checksums.

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "merchantId": "8263015379487437770",
    "merchantSiteId": "39",
    "userPaymentMethods":{
        "pmName": "Credit Card",
        "pmIssuer": "Visa",
        "userId": "259",
        "pmDisplayName": "1111",
        "upoStatus": "0"
    },
    "version": "1",
    "status": "Success",
    "errCode": "0",
    "reason": ""
}

Output Parameters

PARAMETER TYPE DESCRIPTION
merchantId Long Your unique identification number provided by SafeCharge.
merchantSiteId Long Your web site’s unique identification number provided by SafeCharge.
userPaymentMethods Class userPaymentMethod contains:
pmName: Name of the payment method, for example, PayPal or Credit Card.
pmIssuer: Credit Card name (if cc_card or dc_card) - NULL if empty.
userId: Customer’s ID for the payment method.
pmDisplayName: For credit card: last four digits of the card number (…..1111). For APMs, this value represents the user’s account name, such as PayPal email address or Neteller Secure ID.
upoStatus: Indicates if the payment method is suspended for the user. 0 is returned for active payment methods, 1 for suspended payment methods. When a payment method is suspended the customer cannot process transactions through that payment method.
version String The version of the protocol.
status String Indicates if the API call was successful or not:
Success: Successful result.
Error: Unsuccessful result due to some technical failure, for example the request was sent with a parameter out of the allowed range.
errCode Integer Error code when an error occurs.
reason String Reason an error occurred.