API Reference

The Payment Processing API conforms to the design principles of Representational State Transfer (REST). The REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. By default, the response format is XML. If you wish, you can request JSON instead of XML. Your methods will be the standard HTTP methods such as GET, PUT, POST and DELETE.

The API currently supports the following data formats: for requests XML or NVP, and for responses XML, HTML, JSON or NVP with some methods only accepting a subset of these formats. Simply change the format extension to a request or set the HTTP Accept header to get results in the format of your choice.

Methods to retrieve data from the Payment Processing API require a GET request. Methods that submit data require a POST. API methods that require a particular HTTP method will return an error if you do not make your request using the correct method. HTTP Response Codes are meaningful.

Some API methods take optional or requisite parameters. Two things to keep in mind when making requests with parameters:

Because the Payment Processing API is based on open standards, you can use any web development language to access the API.

Every request is authorized and authenticated. Users are authenticated using basic authentication over SSL enabled channel. The Merchant Account configuration is used to authorize the request.

Create a Payment

This attempts to create a transaction. The type of the transaction is determined by the payload of the message.

Fields

Custom Fields

In addition to processing transactions, the Payment Gateway also permits the storage and later retrieval of additional information. The use of 'Custom Fields' permits the client application to store key-value pairs with each transaction.

In the following example, the client application has stored a purchase order, invoice, crm-id, customer tier, and promotional code. This information is also echoed back in any response querying the status of a transaction. It is also possible to see this information in the reporting system.




Instant Payment Notifications

The platform has a built-in notification capability. The Merchant simply sends the notifications instructions as part of each transaction request. Notifications need to be specified as a URL. There are two types of notifications:

  • HTTP(S) (Web Server POST)
  • SMTP (Email prefixed with 'mailto')

It is possible to setup conditional notifications based on the state of the transaction. For example, a Merchant can instruct a notification to only occur on 'failed' or 'successful' transactions. In the following example, the transaction will notify the Merchant's web site for a failed transaction, and send all results to an email address.




Addendum Data

The platform offers vertical market solutions for several industries.

Please refer to Payment Fields for a full list of fields.

Airline Data Example

 


Cruise Data Example

 


Hotel Data Example

 


Query by Transaction ID

Retrieving a transaction using a transaction-id returns a single transaction belonging to a merchant account. The transaction-id node must match the value that was included in the transaction response. An error is returned if the transaction-id is not available or the requested user is not authorized to see the content. The desired content type can be set through the Accept header or by specifying an extension.

URLhttps://hostname/engine/rest/merchants/{merchant-account-id}/payments/{transaction-id}
Response FormatsXML, HTML, JSON
Request MethodsGET

Fields

Sample Request/Response

Sample GET Request:

https://hostname/engine/rest/merchants/ba261be8-af94-11df-ab7800163e5eafd7/payments/048b27e0-9c31-4cab-9eab-3b72b1b4d498

*Note: The response will differ depending on the Transaction Type.

Sample XML GET Response for a purchase:




Query by Group Transaction ID

This returns a group of transactions belonging to a merchant account. An error is returned if the group transaction id is not available or the user is not authorized to see the content. The desired content type can be set through the Accept header or by specifying an extension.

URLhttps://hostname/engine/rest/merchants/{merchant-account-id}/payments/?group_transaction_id={group-transaction-id}
Response  FormatsXML, HTML, JSON
Request MethodsGET

Fields

Sample Request/Response

Sample GET Request:

http://hostname/engine/rest/merchants/1a8b86dc-ca57-461c-a3f0-b4f4de2ed8bb/payments/?group_transaction_id=9b6f1ec9-ba4c-4a09-84dc-1ef9be782fec

*Note: The response will differ depending on the Transaction Type.

Sample GET Response:




Query by Request ID

This returns a single transaction belonging to a merchant account. The request-id attribute must match to a request-id that was submitted during the creation of a transaction. An error is returned if the request id is not available or the user is not authorized to see the content. The desired content type can be set through the Accept header or by specifying an extension.

URLhttps://hostname/engine/rest/merchants/{merchant-account-id}/payments/?request_id={request-id}
Response  FormatsXML, HTML, JSON
Request MethodsGET

In addition up to 50 transactions can be returned in a single response by utilizing a wildcard character (*) as part of the request-id.
for example: GET https://hostname/engine/rest/merchants/c3671cf9-c775-4e39-8d67-31ce24094682/payments/?request_id=00a7a0f6-7dfa-476f-9c11-807f1b3a9f32*
will return multiple transactions:



Fields

Sample Request/Response

Sample GET Request:

https://hostname/engine/rest/merchants/ba261be8-af94-11df-ab78-00163e5eafd7/payments/?request_id=048b27e0-9c31-4cab-9eab-3b72b1b4d498

*Note: The response will differ depending on the Transaction Type.

Query by API Transaction ID

This returns a single transaction belonging to a merchant account and should be used in the case where merchant transactions are processed over a white-label API. The api-transaction-id parameter must match to a transaction-id that was returned over a white-label API. Please consult your sales representative if you are unsure of the value for the api-id parameter.

The desired content type can be set through the Accept header or by specifying an extension.

/merchants/{ma}/apis/{api_id}/payments/{api_transaction_id}
URLhttps://hostname/engine/rest/merchants/{ma}/apis/{api_id}/payments/{api_transaction_id}
Response  FormatsXML, HTML, JSON
Request MethodsGET

Fields

Sample Request/Response

Sample GET Request:

https://hostname/engine/rest/merchants/ba261be8-af94-11df-ab78-00163e5eafd7/apis/elastic-api/payments/C862185135969856615803

*Note: The response will differ depending on the Transaction Type.

Sample XML GET Response for a purchase:




Transaction Simulation

A Merchant Account can send a special message, requesting that the result echoes back a specific set of Transaction Statuses. The following characteristics apply:

  • Any merchant account can be used for test simulation, in production or any other environment.
  • Existing fields can be populated with information notifying the engine that this is a test transaction. This allows standard payment attributes to be used in a Merchant's existing Order Management, Internet Booking Engine, Virtual Terminal, or any other client applications.
  • Test Transactions are never settled.
  • It is possible to simulate a successful transaction by sending a transaction status of "20x.xxxx". Any other requested Transaction Status Code will result in a transaction state of 'failed'.
  • It is possible to simulate a timeout scenario by delaying the response from the engine by client application's timeout setting.
At times, it may be required to simulate one or more valid Transaction Statuses. The client application indicates that it wishes to have certain Transaction Statuses echoed back, and the Payment Service does so in the response.

Following is the behaviour:
  • Any invalid/empty Transaction Statuses are not simulated. See Valid Transaction Statuses.
  • The simulation is valid for all Payment Methods.
  • The payment being requested does not go to any acquirer/provider. The transaction status simulation is typically used to simulate the status from the acquirer/provider.
  • The engine performs basic data validation in order to store the data in the database. In case of any failure, the requested transaction statuses are NOT echoed back. The validation errors are returned instead.
  • The transaction can be searched in the reporting site.
  • All other aspects of the Payment Processing are respected, including Instant Payment Notification, Reconciliation Services, etc.
  • All Test Transactions will have the Last Transaction Status of "100.5555 warning: Your transaction is in test mode."
  • Merchant Account must have a "Test Token" assigned to enable Transaction Status Simulation.

Warning: If "100.5555" is not returned, the Transaction was NOT in Transaction Processing Test Mode, and was processed live. Watch for this to ensure the intended effect.

In order to simulate a set of Transaction Statuses, the following two fields are required:

  • account-holder/lastname
    A "Test Token" that is issued in order to enable Simulation of Transaction Statuses.
  • accountholder/address/street1
    The valid transaction status to be simulated. If multiple are required, a comma-delimited set of transaction statuses.
    Optional timeout simulation: An instruction to have the server disconnect the session after a specified number of seconds (maximum 300 seconds), without responding. Format: "timeout-<timeout timespan in seconds>".

Sample Request: transaction status simulation, credit card issuer declined.




Sample Response




Timeout Simulation

At times, it may be required to simulate the system not responding to the client application for an extended period of time. The client application must specify that a timeout value of n seconds by using the <street1> field in conjunction with the "Test Token" in <last-name> field. The value of n should be more than the client application's timeout setting.

Sample Request: transaction status simulation, successful credit card transaction that responded after 180 seconds.




Sample Response




Referenced Transaction Simulation

At times, it may be required to simulate a transaction followed by another one referencing the first, such as a credit card authorization followed by a capture. In the reference transactions <street1> field is not used. As such, the client application indicates the expected status of the referenced transaction in the initial transaction. E.g. excepted status code of a capture transaction must be indicated in the initial authorization. This is indicated in the <street1> field with a grammar including transaction type abbreviation. The ordering of the status codes in the <street1> field is significant. Payment Service analyse the transaction type in a payment workflow or group and applies the status code as mentioned in the original transaction and returns it to the client application.

In the following sample, the client application would like to simulate a successful zero dollar authorization followed by credit card declined during the charge:

  1. Zero Dollar Authorization: 201.0000
  2. Purchase: 500.1053
This expected status codes were set during the ZDA request as follows:
<street1>AO-201.0000,P-500.1053</street1>

1st Request: Zero Dollar Authorization




1st Response




2nd Request: Purchase




2nd Response




Tokenization

Every card number that accompanies a transaction is subsequently tokenized. Regardless of the outcome of the transaction, this token can be subsequently used instead of the clear card account number, in any subsequent transaction. This means that the client system never needs to store the sensitive card information, helping to reduce PCI DSS Compliance issues.

It is also possible to submit a Tokenization Transaction, whereby the transaction does not process a payment. It simply tokenizes information. The Detokenize Transaction can be utilized to subsequently retrieve this tokenized information.

Tokenize Credit Card

The tokenize Transaction Type simply converts credit card information into a token that can be used in subsequent Payment Transactions, instead of the actual credit card information.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Sample XML

Sample Request



Sample Response




Detokenize Credit Card

The detokenize Transaction Type is the inverse of the tokenize Transaction Type. In that a token-id is provided to retrieve the original information.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Sample XML

Sample Request



Sample Response




Card Token Additional Data

When submitting transactions using card token, it is possible to override and/or provide additional fields alongside the card token. Fields such as expiration-month, expiration-year, card-security-code, first-name, last-name can be supplied alongside a card token.

The following snippet shows additional data being submitted in conjunction with a card token:

  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
  </account-holder>
  <card-token>
    <token-id>4622861590081111</token-id>
  </card-token>
  <card>
    <expiration-month>12</expiration-month>
    <expiration-year>2020</expiration-year>
    <card-security-code>123</card-security-code>
  </card> 
...

Tokenize Loyalty Card

The tokenize transaction type simply converts loyalty card information into a token that can be used in subsequent Payment Transactions, instead of the actual loyalty card information.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Sample XML

Sample Request



Sample Response



Detokenize Loyalty Card

The detokenize transaction type is the inverse of the loyalty tokenize transaction type. In that a token-id is provided to retrieve the original information.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Sample XML

Sample Request



Sample Response



Hosted Payment Page

Hosted Payment Page stands for secure, flexible, easy and transparent payment processing. It provides all payment methods in ONE solution, from credit cards, 3D secure, and direct debits to online payments, mobile payments, alternate payment methods and industry-specific solutions.

Hosted Payment Page integration involves the merchant redirecting the consumer to the Payment Page along with information about the transaction and a secure digital signature.
Merchants remain PCI SAQ-A compliant as the credit card information is captured and stored by the payment gateway.

The Payment Page can be accessed via https://hostname/engine/hpp/
Please contact your support representative for the exact URL.

Workflow

Hosted Payment Page provides a generic workflow available for various payment methods.

  1. Customer checks out with the purchased goods / services.
  2. Merchant system redirects to the Hosted Payment Page URL with a digitally signed payment request.
  3. The Payment Gateway validates the signature and returns the list of Payment Methods to which the merchant has access with the associated redirect URL.
  4. The Hosted Payment Page displays the payment methods from which the customer may choose.
    Please note: this payment method selection may optionally be skipped based on the merchant's account configuration.
    Depending on the chosen payment method and the respective specifics of this payment method, the Hosted Payment Page then displays the relevant input fields.
  5. The Payment Page posts the payment transaction to the Payment Gateway.
  6. The Payment Gateway processes the payment with the respective financial institution.
  7. The Payment Gateway returns the final response to the Payment Page, which is a digitally signed response message.
  8. The Payment Page posts the digitally signed response back to the merchant's success or failure URL.
  9. Optionally, the merchant's system validates the signature, and decodes the response message. Finally, the customer (the customer's browser) is presented with the payment status.

Security

As payment information is exchanged between the merchant's system, the consumer's browser, and the Payment Gateway, it is important that the data exchange safeguards against man-in-middle attacks.

Transmitted messages must have the following attributes:

  • Payment request message as described here.
  • Digitally signed with a symmetric signature (SHA256).

  • Confidentiality is the property of preventing disclosure of information to unauthorized individuals or systems. The confidentiality of the data is addressed using a SSL based communication channel. The message payload does not contain any confidential information like card number or account number etc. Hence the message will not be further encrypted.
  • Integrity means that data cannot be modified without authorization. This is achieved by calculating the hash on the payload references.
  • Non-repudiation implies one's intention to fulfill their obligations to a contract. This is achieved by signing the digitally calculated hash.
  • Authentication ensures that the identity of the sender can be determined by anyone. This is achieved by using the PKI cryptography infrastructure.

Secret Key Exchange

To ensure the authenticity of the request and response messages, it is required that a Secret Key is shared with the merchant.

The Secret Key is used in generation of the request_signature and response_signature fields.

It is important that the Secret Key is never shared with anyone and is protected within the Merchant Website (only used in server side code for generating the Request Signature or validating the Response Signature).

The Secret Key will be communicated at the time of Merchant Account setup. Please contact your support representative if you did not receive a Secret Key or require Secret Key regeneration.

Digital Signature

Hosted Payment Page uses a digital SHA-256 signature for all message exchanges. The signature is a mathematical scheme for demonstrating the authenticity of a digital message or document. A valid digital signature gives a recipient reason to believe that the message was created by a known sender, and that it was not altered in transit.

SHA-256 Request Signature

When the Merchant creates the client side HTML form, the following values are to be concatenated, leading and trailing space removed, and SHA-256 applied to the combined string

  1. request_time_stamp
  2. request_id
  3. merchant_account_id
  4. transaction_type
  5. requested_amount
  6. requested_amount_currency
  7. redirect_url
  8. ip_address
  9. [Secret Key] (generated by an administrator)

The SHA-256 hash value is then presented on the Merchants client side form as a hidden field.

Please note the order of the fields is important. Also, note the same values used in the Request Signature must be placed into the client side form (with the exception of the Secret Key).

For field definitions please refer to Request Fields

An example of Request Signature generation is as follows:

request_time_stamp          = '20120430123012'
request_id                  = 'order-12345'
merchant_account_id         = 'b19fb056-d8da-449b-ac85-cfbfd0558914'
transaction_type            = 'purchase'
requested_amount            = '1.01'
requested_amount_currency   = 'USD'
redirect_url                = ''
ip_address                  = '127.0.0.1'
secret_key                  = 'efabf47b-e43b-4785-873f-1c5bc65b7cd2'

Pre SHA-256 string
20120430123012order-12345b19fb056-d8da-449b-ac85-cfbfd0558914purchase1.01USD127.0.0.1efabf47b-e43b-4785-873f-1c5bc65b7cd2

SHA-256 signature
e93ed221efb8f6048df31794609d9557f65f175659e4928d10463b8998e3f61f

Signed Example Request




Signed Example Response




SHA-256 Response Signature

Within the response message the following values are concatenated, leading and trailing space removed, and SHA-256 applied to the combined string:

  1. merchant_account_id
  2. transaction_id
  3. request_id
  4. transaction_type
  5. transaction_state
  6. completion_time_stamp
  7. token_id
  8. masked_account_number
  9. ip_address
  10. authorization_code
  11. [Secret Key] (generated by an administrator)

Please note the order of the fields is important. For field definitions refer to Response Fields.

It's strongly recommended that the merchant's system validate the signature before offering goods or services.

Signature Generation Code Samples

PHP




C# / ASP.NET




Java




Groovy




Fields

The following fields must be POSTed to https://hostname/engine/hpp/
Please contact your support representative for the exact URL.

Request Fields

Response Fields

Querying Payments

In the event that a payment is submitted and no response is received by the Merchant, a Payment Status can be retrieved. Details on how to query a payment can be found in Query by Request ID.

Consumer Redirects

Upon a successful or failed Payment Page transaction, the consumer is redirected (via automated HTTP POST) back to the successful or failed URL along with the digitally signed payment message (please refer to Signed Example Response).

It is strongly recommended merchants verify the signature and/or utilize IPN to determine a transaction's final status.

Preselection

Hosted Payment Page supports automatic selection of payment methods in order to bypass rendering of the Hosted Payment Page.

Simply set payment_method in the initial payment request to force selection of a specific payment method.

Prepopulation

Hosted Payment Page supports prepopulation of consumer information to reduce or completely eliminate consumer data entry.

Consumer information such as name, order, and address information can be sent within the initial payment request. Hosted Payment Page will use these values as the default, which can be manually overriden by the consumer.

In addition, sending all credit card fields account_number, card_type, card_security_code, expiration_year, and expiration_month will enable the transaction to be processed without consumer input or interaction. Please see SilentPay for more information.

SilentPay

When processing credit card transactions via Hosted Payment Page there is the option to completely bypass rendering of the Hosted Payment Page.

Subsequent processing redirects such as 3D secure are automatically handled.

To enable SilentPay processing the merchant must pass the following fields within the initial payment request:

  • account_number
  • card_type
  • card_security_code
  • expiration_year
  • expiration_month

Configuration

Payment methods, transaction types, card types, and supported currencies are configured within the Payment Gateway. Please contact your support representative if any of the above is not yet available.

For the list of permissible payment methods, transaction types, currencies, and country values please refer to the Reference section.

Success and Failure Redirect URLs

Default Success & Failure URLs are configured during merchant account setup. To adjust these please contact technical support.

Internationalization

The Hosted Payment Page has been designed with multilingual support. Consumers can choose from over 50 languages for instant translation.

Asymmetric Encryption

Security

Transmitted messages must have the following attributes:

  • Payment request message as described here.
  • Digitally signed with either asymmetric (DSA or RSA)
  • Base64 encoded

Asymmetric Digital Signature

Hosted Payment Page can use an XML signature for all message exchange between systems. Both DSA and RSA keys are supported.

An XML signature is enclosed in the XML envelop of the message payload. RFC 2828 defines a digital signature as "a value computed with a cryptographic algorithm and appended to a data object in such a way that any recipient of the data can use the signature to verify the data's origin and integrity".

The high level process of asymmetric signature generation and validation is depicted below:

The XML Signature has advantages over any proprietary signing/hashing algorithm. Open standard libraries are available that make signature generation and the validation process rather seamless. Secondly, the Signature contains meta-information about the cryptographic algorithms used and which references are used for the signature generation and validation. This eliminates the need of prior negotiation for the signature strategies.

XML signatures are often described as being of one or more of three types:

  • A detached signature is over data that is external to the Signature element. This could be data outside of the document.
  • An enveloping signature is over data that is inside the Signature element.
  • An enveloped signature is a signature that is over data that contains the Signature element itself, such as the entire document.
  • An enveloped signature is used for the Hosted Payment Page message exchange.

Signed XML Sample




Asymmetric Key Exchange

Since the PKI infrastructure would be used for all message exchange, it is required that public keys are exchanged between the merchant and Payment Gateway. This can be done either through email or an URL where the certificate can be downloaded.

Embedded Payment Page

Hosted Payment Page requires a redirect from the merchant's website to the Payment Gateway. As this might not be the preferred customer experience, Embedded Payment Page is available as an alternative option to provide the same level of payment options while ensuring a better customer experience.

Embedded Payment Page displays the payment page as an overlay (lightbox) on top of the merchant's website. All payment options supported by Hosted Payment Page are available via Embedded Payment Page.
Merchants remain PCI SAQ-A compliant as the credit card information is captured and stored by the Payment Gateway.

Workflow

Embedded Payment Page provides a generic workflow available for various payment methods.

  1. Customer checks out with the purchased goods / services.
  2. Merchant system sends a request to the Payment Gateway with a digitally signed payment request.
  3. The Payment Gateway validates the signature and returns the list of Payment Methods to which the merchant has access with the associated redirect URL.
  4. The Payment Page displays the payment methods from which the customer may choose.
    Depending on the chosen payment method and the respective specifics of this payment method, the Payment Page then displays the relevant input fields.
    Please note: the payment method selection may optionally be skipped based on the merchant's account configuration.
  5. The Payment Page posts the payment transaction to the Payment Gateway.
  6. The Payment Gateway processes the payment with the respective financial institution.
  7. The Payment Gateway returns the final response to the Payment Page, which is a digitally signed response message.
  8. The Payment Page posts the digitally signed response back to the merchant's success or failure URL.
  9. Optionally, the merchant's system validates the signature, and decodes the response message. Finally, the customer (the customer's browser) is presented with the payment status.

Fields

Please refer to Hosted Payment Page Fields for a full list of fields.

Integration

Embedded Payment Page utilizes the same key exchange and digital signature format as Hosted Payment Page.

An additional javascript library and a function call of the library provides the integration to call the lightbox.

Javascript library

<script src="https://hostname/engine/hpp/paymentPageLoader.js" type="text/javascript"></script>

Function call

ElasticPaymentPage.embeddedPay(requestedData);

Credit Card Integration Request

 


Seamless Payment Page

Seamless Payment Page embeds the payment form within the merchant's website using an iFrame. With this feature, merchants are provided with the ability to incorporate the Payment Gateway's payment form into the merchant's checkout page. This reduces the merchant's PCI compliance requirements (Merchants remain PCI SAQ-A compliant) while providing the experience of a payment being an integral part of the merchant's website.

This approach provides customers a seamless shopping experience by

  1. Avoiding browser redirects
  2. Allowing merchants to fully control the look and feel of the payment form
  3. Providing a sophisticated checkout flow that collects payment data, then allowing customers to review the order before confirming the payment

Workflow

To ensure a seamless and PCI compliant integration, the Payment Gateway serves the complete payment form as an HTML iFrame, which ensures that attacker or malicious scripts will not have access to data entered on the merchant's page. The form is then submitted directly to the Payment Gateway over a secure TLS channel, so the data is securely transported.

  1. Customer checks out with the purchased goods / services.
  2. Merchant system sends a render form request to the Payment Gateway with a digitally signed payment request.
    Please note: If merchant supports multiple payment methods, merchant system will prompt customer for the preferred payment method prior to this step
  3. The Payment Gateway validates the signature and renders the payment form.
  4. The iFrame posts the payment transaction to the Payment Gateway.
  5. The Payment Gateway processes the payment with the respective financial institution.
  6. The Payment Gateway returns the final response to the merchant system, which is a digitally signed response message.
  7. The merchant's system validates the signature, and decodes the response message.
  8. Finally, the customer (the customer's browser) is presented with the payment status.

Fields

Please refer to Hosted Payment Page Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Integration

Seamless Payment Page utilizes the same key exchange and digital signature format as Hosted Payment Page.

An additional javascript library provides additional function calls of the library provides the integration to perform the form rendering and payment submission.

Javascript library

<script src="https://hostname/engine/hpp/paymentPageLoader.js" type="text/javascript"></script>

The library provides the following functions

Render Payment Form

This call renders the payment form with the following required parameters

  • request data, same as for Hosted Payment Page and similar to REST API integration
  • id of the element where the form will be rendered
  • functions to handle call-back data (response is the only parameter of the functions) in cases of success and error

ElasticPaymentPage.seamlessRenderForm({
  requestData : requestData,
  wrappingDivId : "seamless-target",
  onSuccess : processSuccessResult,
  onError : processErrorResult
});

Submit Form

This call submits the data within the rendered payment form with the following parameters

  • request data (optional)
  • functions to handle call-back data (response is the only parameter of the functions) in cases of success and error

ElasticPaymentPage.seamlessSubmitForm({
  requestData : requestData,
  onSuccess : processSuccessResult,
  onError : processErrorResult
});

Submit Payment

This call submits the payment form as an independent function (without seamlessRenderForm and seamlessPay) or when the payment process is decoupled (ie. merchant displays a summary page between rendering of payment form to actual submission of payment). Parameters include

  • request data (Includes parent_transaction_id for link to original rendering of payment form)
  • functions to handle call-back data (response is the only parameter of the functions) in cases of success and error

ElasticPaymentPage.seamlessPay({
  requestData : requestData,
  onSuccess : processSuccessResult,
  onError : processErrorResult
});

Change Language

This call changes the form's locale to the preferred the ISO code.

ElasticPaymentPage.seamlessChangeLocale("en");

Form Validation

Merchants can choose to validate the payment form by using the seamlessFormIsValid call or to validate the data in the payment form by using the seamlessValidateForm call.
The payment data is always validated when the form is submitted. Parameters include

  • function to handle call-back data
ElasticPaymentPage.seamlessFormIsValid({
  onValidationResult : processValidationResult,
}

ElasticPaymentPage.seamlessValidateForm({ onValidationResult : processValidationResult, }

Samples

Single step payment

Render Form Request



Render Form Response



Submit Form Request



Submit Form Response




Decouple card data collection and payment

Merchants can choose to display a recap order page between the payment data collection page and the actual payment submission. In such cases, the merchant can use the payment form to perform a:

  1. authorization-only transaction that may be later referenced by a regular authorization or purchase. The advantage is that the card data (and CVC) is verified by the issuer. This requires the acquirer to be able to support this transaction-type.
    Please note: Not all acquirers support this transaction-type.
  2. tokenize where transaction where a token (non-sensitive data) is returned to merchant to be used during the actual authorization or purchase.
In either case, sensitive payment data will not touch any of the merchant's systems.

Render Form Request




Render Form Response




Submit Form Request




Submit Form Response




Payment Request




Payment Response




3-D Secure

When a merchant is configured for 3-D Secure payments or when attempt_three_d flag is set to true, a check-enrollment transaction will be attempted during the submit form stage.
If the card is enrolled for 3-D Secure, a success response will be sent back via the callback specified with the acs_url, pareq, nonce3d.
The merchant should then proceed to handle the 3-D Secure process per normal.

3-D Secure Submit Form Response



Payment Page Customization

The Payment Pages are customizable to be similar to the merchant's website in look and feel. This provides customers with a better payment experience.

Please contact your support representative for the availability of the feature.

Hosted Payment Page Customization

We recommend using a browser editor such as FireFox's Web Developer Tool or Google's Chrome DevTools for CSS editing.

  1. Refer to
  2. Provide the psp_name field with the preferred value eg. "demo", "demofull"
  3. Initiate a transaction and get redirected to the Hosted Payment Page
  4. Access the editor and review the CSS files loaded for the Hosted Payment Page for a specific theme.
  5. The customization files are available in the same folder name as the psp_name submitted. The css file that contains the elements to be overwritten are found in embeddedHpp.css


  6. Adjust the values of the elements to the preferred values
  7. If the element to be adjusted is not available in embeddedHpp.css, review the element information
  8. Add the element information to embeddedHpp.css and overwrite the value with the preferred value.
  9. Review the changes and save the files in the folder with the preferred naming
    Please note: The maximum logo size is 45px in height, 200px in width.

Once the files are saved, please provide the files to your support representative.

Embedded Payment Page Customization

Please follow the same steps as the Hosted Payment Page custommization to provide the customization files.

Seamless Payment Page Customization

A configuration UI has been created to provide a simple customization and quick preview for the seamless customization.

The configuration UI is available at https://hostname/engine/rest/config/seamless/ui/
Please contact your support representative for the exact URL and login credentials.

For production environment, please submit the exported file to your support representative. This will be reviewed and imported into the account for activation.

  1. Login to the configuration UI
  2. Provide the Merchant Account ID of the account to be customized


  3. Once the information is provided, the list of the merchant's configured templates is displayed in the left menu. Template specific details are displayed in tabs for each template.


  4. If there are no existing template, "Add a template" by choosing from the list of available options. The fastest and easiest is to clone from the existing credit card templates.
    This is suitable for the initial customization or where basic customizations are required as it forms the base to start the customization.


  5. Adjust the template to the preferred values under each tab. Click the save button to save the changes.
  6. Review the changes by previewing the saved template. Click on the preview button and provide additional information requested.


Resource management



All resources related to a template can be found in the "Template Resources" tab. Resources can be added when it is required.

  • To select a resource, double click on it in Available Resources list or select it and use arrows between list boxes.
  • To deselect a resource, double click on it in Selected Resources list or select it and use arrows between list boxes.
  • To change the order of the resources, use the arrows next to the Selected Resources list. The resource order is important when loading libraries with dependencies.

Translations management



Template specific i18n translations can be made via the "Template translations" tab.

  • New translations can be created, existing ones can be updated or deleted. Changes are applied once whole template is successfully saved.
  • Each i18n configuration must be preceded by the language code (2-letter case insensitive code enclosed in the square brackets) followed by all required translation mappings.
  • Translation mappings must follow the key=value format and each mapping is separated by a new line. Translation key can only contain letters, numeric, dash or underscore characters.
  • To override field values or error messages or fields that that are not in the existing templates, retrieve the field name from the browser. Add the field name to the translation template and the preferred message.

Transparent Post

Transparent Post provides a seamless user experience by allowing Merchants to place the entire payment form within their website. Sensitive payment information, such as account number and CVC, are submitted directly to the secure processing environment. As a result, sensitive information nevers flows through the Merchant system, reducing PCI DSS requirements to the lowest level possible. As messages flow through the consumer browser, stricter security measures need to be employed.

Integration with Transparent Post is performed by the Merchant generating a client-side HTML form with prefilled fields and then generating a SHA-256 signature based on the values of the predefined fields. The consumer submits the client-side form directly to the secure Payment Gateway. Once the payment is processed, the consumer is redirected directly back to the Merchant website for order completion.

The URL for the Transparent Post varies depending on the installation domain.

Transparent Post can be accessed via https://hostname/engine/hpp/tpost
Please contact your support representative for the exact URL.

Workflow

  1. Consumer checks out with the purchased goods / services.
  2. Merchant system creates client-side payment form including digitally signed payment request.
  3. Customer provides payment information (account number, expiration, CVC) and submits the form directly to Payment Gateway via HTTP Post.
  4. The Payment Gateway validates the signature and processes the payment with the respective financial institution.
  5. The Payment Gateway redirects the customer back to the merchant's website together with the final response, which is a digitally signed response message.
  6. The merchant's system validates the signature, and presents the payment status to the customer.

Integration

Transparent Post utilizes the same key exchange, digital signature format and fields as Hosted Payment Page.

HTML Form Examples

Below are simplified examples of creating a HTML form within the Merchant's website. Cosmetic features are removed, as well as recommended features such as client-side validation. Ensure that:

  • Form method is set to POST
  • Form enctype is "application/x-www-form-urlencoded"
  • Form accept-charset is "UTF-8"
  • The Secret Key is never visible in client-side code
  • The exact values used in Request Signature generation are also placed into the form (generally as hidden values).

Payment Example




Tokenize Example



Credit Card Payments

Transaction Flow

via REST API

Credit Card REST Transaction Flow

via Hosted Payment Page

Hosted Payment Page Transaction Flow

Please see Hosted Payment Page for more information.

Sample REST XML

Sample Request




Sample Response




Sample REST NVP

NVP is a canonical form of the XML Representation. The following is a sample. Field names are derived from the XML Element Names by using an underscore delimiter. All fields should be URL-encoded.




3-D Secure

3-D Secure is a protocol by Visa and Mastercard that provides secure authentication and processing of online payments. Merchants wishing to comply need to integrate the specific 3-D requests and payment parameters.

The Three Domain (3-D) Secure initiative by VISA is a new payment standard for secure handling of credit card transactions in electronic commerce. This provides Issuers with the ability to authenticate cardholders during an online purchase. Branded as Verified by Visa (VbV) and MasterCard SecureCode (MCSC), 3-D Secure is designed to clearly identify cardholders and accelerate the growth of electronic commerce through increased consumer confidence.

Authentication is accomplished by verification of certain data which is maintained by the card issuing bank and identifies the individual making an online purchase as the legal owner of the card used. 3-D Secure is more than a payment authentication method or a technology definition. It is a model to isolate the liabilities of the various parties involved in the payment transaction cycle. The payment environment requires the participating cardholder to be registered (enrolled) for the process with his issuing bank. In essence, all parties involved in the payment flow must support the 3-D secure transactions. The 3-D framework requires the card issuing and acquiring banks to provide cardholders and merchants with an authentication methodology, without binding them to proprietary technology.

Merchant Plug-In

A Merchant Plug-In is a software module which provides a communication interface between the merchant and the Visa or MasterCard directory servers. It can be integrated in the merchant website or it may be hosted by a service provider or an acquirer. The main functions of an MPI are to verify the card issuers digital signature used in the authentication process, validate enrollment and authentication response messages, encrypt and store passwords and certificates, and retrieve payment records and associated card details to resolve transaction disputes. Merchants can choose to leverage the enrollment check and payment authentication using a hosted or an integrated MPI. Both options will notify the merchant if either of the two validations failed.

Payments need to be submitted with the relevant 3-D Secure artifacts obtained from the MPI and to see the detailed 3-D-Secure Process Flow.

Merchant Plug-In (MPI)

This document describes the integrated MPI for merchants that wish to utilize our 3-D Secure MPI Provider. This solution performs all of the relevant validations and exchanges as required by Visa and Mastercard.

3rd Party MPI

If a merchant wishes to use a 3rd Party MPI, then only payments need to be submitted with the relevant 3-D Secure artifacts obtained from the 3rd Party MPI.

Process Flow

Processing 3-D Secure transactions differs from standard payment processing. Merchants must construct and route their transaction requests accordingly. The three necessary steps for processing are:

  • Check Enrollment - consists of a single request/response communication that verifies if the card number is eligible and participates in the 3-D Program.
  • Customer ACS Communication - redirects the Customer to the ACS URL, a webpage provided of the cardholder's bank. This allows the Customer to authenticate himself by entering his 3-D credentials.
  • Check Payer Response - Validation of the authentication result. This is used in conjunction with check enrollment.
3-D Secure Enrollment Flow

The diagram below illustrates the detailed 3-D Secure process flow:

3-D Secure Detailed Process Flow

Check Enrollment

The Payment Processing API permits merchants to check if a card/cardholder is enrolled in the 3-D Secure program. To verify Enrollment status, the merchant system sends a transaction request to our MPI which in turn posts an Enrollment check request (VEReq) to the Visa or MasterCard directory server. In an exchange of messages the directory communicates with the ACS of the card issuer, if required, to determine if the cardholder is enrolled for 3-D Secure. A response message (VERes) is returned by the ACS to the MPI to prove that the cardholder is enrolled or that authentication has been attempted.

Fields

The same Payment Fields are required, with no new input fields, and 2 additional 3-D Secure Output Fields. Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

The following two response fields are specific to 3-D Secure.

Sample XML

Sample Request





Sample Response




ACS Redirect

In addition to the interface setup between the merchant and us, the successful 3-D Secure implementation requires some interaction between the merchant and the issuing bank via the cardholder browser. There is NO interaction with us for this step. For the 3-D authentication to work, it is imperative that the merchant communicates with the ACS by SSL-encrypted HTTP POST request. In setting up the HTTPS Post authentication request, the merchant must ensure that following the enrollment check the purchase order is redirected from the merchant server to the card issuer's Access Control Server (ACS).

Fields

ACS HTTPS Redirect

In case a card is eligible and enrolled ('check-enrollment', Transaction Status Code = 200.0000) the merchant system must redirect the customer's browser to the ACS URL provided in the Verify 3-D Participation response. If the card is not enrolled (('check-enrollment', Transaction Status Code = 500.1072) , the ACS redirect must be skipped.

This HTTPS POST message includes the web address (URL) of the ACS and three hidden input types: <PaReq>, <TermUrl> and <MD>. The TermUrl defines the web address of the merchant site to which the issuer returns the Payment Authentication Response (PARes) message. The parameter type <MD> is reserved for specific merchant data. Although this field is mandatory, it does not need to have a value defined. If this input type is omitted an authentication error will occur and the payment process is aborted. The MD may be useful for retrieving transaction data from the database or recalling a transaction. The data is returned untouched by the ACS with the Payment Authentication Response (PARes).

Example: Auto submission POST Request




ACS HTTPS Redirect to TERM-URL

The cardholder's browser passes the encrypted PAReq message unprocessed to the ACS. This step is made up of two phases: The server invokes an authentication popup or inline window in the cardholder's browser. The cardholder enters a password in the authentication window and returns the data to the ACS.

The ACS authenticates the cardholder's password, constructs the verification ID, and posts an SSL-encrypted and digitally signed Payment Authentication Response (PARes) to the TermURL via the Account Holder's browser. Encryption and signature ensure that the content cannot be modified during transit.

The cardholder browser redirects the fully encrypted PARes to the merchant's server address specified as TermUrl. The response message contains the results of the cardholder authentication and the untouched merchant data (MD).

Check Payer Response

The merchant has received the PARes via the TermUrl. The PARes is a digitally signed XML document and has to be forwarded to the Payment Gateway for validation. This is done with the Check Payer Response. This request should be used in case you are using the Payment Processing API as 'MPI only'. Otherwise the PARes should be included along with the subsequent payment request.

NOTE: To ensure a unique transaction flow the Check Payer Response should be called for ALL 3-D transactions regardless of the enrollment status. The Check Payer Response includes the ECI which is needed for further payment processing.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Sample XML

Sample Request




Sample Response




Payment Request with PARes

The merchant has received the PARes via the TermUrl. The PARes is forwarded to the Payment Gateway along with payment request.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

The parent-transaction-id supplied is the transaction-id of the 'check-enrollment' response. The PARes is received after the dialogue with the issuing bank.

Sample XML

Sample Request




Sample Response




Payment Request with 3rd Party MPI

This scenario is applicable when the merchant uses an external MPI in conjunction with our Payment Gateway to the acquiring network. The protocol is exactly the same as defined for authorization or purchase request above. Only the relevant 3-D artifacts should be included in addition, conditional on their availability. The response remains same as defined above.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Sample XML

Sample Request




Apple Pay

Apple Pay works with the iPhone 6 and 6 Plus via an near field communication (NFC) antenna design, a secure element and the Touch ID function. Apple Pay can be set up easily, with the user simply adding their credit or debit card linked to the iTunes Store to their account. Apple Pay will also be compatible with the recently announced Apple Watch, which is set to expand the Apple Pay service to more than 200 million users of the iPhone 5, 5c and 5s.

Apple Pay supports credit and debit cards from the three major payment organisations, namely American Express, MasterCard and Visa. When using Apple Pay in a shop, restaurant or other retailer, the name, credit card number and security code are not visible to others.

Transactions are authorised with a unique number which is used by the device account number. Instead of the security code on the back of the card, Apple Pay generates a dynamic security code to guarantee the security of every transaction.

In-app online shopping with the iPhone is at your fingertips. Users can pay for physical goods and services including clothes, electronics, health and beauty artefacts, tickets and much more with Touch ID. The payment process is confirmed in a single touch. The user need not enter any account, despatch or invoicing information. The card data is handled with confidentiality meaning online retailers will not be granted access.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

REST API XML Samples

Successful XML Request




Successful XML Response



Card Present

The Payment Gateway also supports card present transactions with the following additional elements to cater for card present data: Card present transaction processing can be in the form of a point of sale terminal transaction processed online (and/or offline) or a mobile device transaction initiated using a mobile SDK. For mobile device initiated transactions, there is typically a backend server that integrates to the Payment Gateway for payment transactions processing although this is not mandatory.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Host Capture

Host Capture enables a merchant's successful authorization transactions to be automatically captured based on multiple currencies, card types, and time zone without requiring further action from the merchant.

While capturing transactions in real-time offers more control to the merchant, Host Capture is easier to implement and support.

For more information or to have Host Capture configured please contact your support representative.

Alternative Payments

Integration Options

REST API

Use this integration when you desire finer control over the payment experience such as handling payment method selection, 3D secure, redirect methods, etc. Your integration will need to initiate the payment and then redirect the consumer to the payment-method-url where the consumer will complete the payment process. Once the payment is complete, your system will receive an IPN containing the status of the payment. Usually, the final status is received within seconds, however, it may take up to a few days depending on the respective payment method.

URLhttps://hostname/engine/rest/paymentmethods/
Request FormatsXML
Response FormatsXML
Request MethodsPOST
Transaction TypeDEBIT




Hosted Payment Page

To reduce integration efforts it is recommended to integrate to Hosted Payment Page. This will reduce a number of integration points including payment method selection, redirection handling, and payment method specific caveats. In the event that online reference transactions (such as refund, void, capture) are required without the use of Enterprise Portal, then a REST API integration is also required.

URLhttps://hostname/engine/hpp/
Request FormatsNVP
Response FormatsNVP
Request MethodsPOST
Transaction TypeDEBIT

Alipay Cross Border

Alipay (www.alipay.com) is China's leading third-party online payment solution, providing an easy, safe and secure way for millions of individuals and businesses to make and receive payments on the Internet. As of September 2011, Alipay had more than 600 million registered users and facilitated around 11 million transactions daily. Alipay provides an escrow payment service that reduces transaction risk for online consumers. Shoppers have the ability to verify whether they are happy with goods they have purchased before releasing funds to the seller.

Please refer to the generic REST or generic Hosted Payment Page integration.

Transaction Flow

Alipay Cross Border Transaction Flow

China Pay

Chinapay is controlled by China UnionPay bank card professional services company and is mainly engaged in online payment channels and other emerging Internet-based, enterprise B2B account payment, telephone payment, online bank transfer, online fund transactions, corporate public funds for private payment, pay self-service terminals and other bank card online payment and value-added services.

Please refer to the generic REST or generic Hosted Payment Page integration.

Transaction Flow

Chinapay Transaction Flow

CIMB Clicks

The CIMB payment system is extensively used throughout Asia. Every CIMB Bank customer can use it to make quick and easy online payments. Available in Malaysia, Philippines, Singapore

Please refer to the generic REST or generic Hosted Payment Page integration.

DBS PayLah

DBS PayLah! is a mobile wallet provided to customers of DBS (Singapore). Customers can choose to pay with their mobile wallet during the checkout process.

Once selected, customers will be prompted on their mobile phone's PayLah! app via a push notification to confirm the payment.

Funds will be deducted from the customer's DBS PayLah! mobile wallet.

Please refer to the generic REST or generic Hosted Payment Page integration.

Direktuberweisung

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

REST API XML Samples

Successful XML Request


	
	
	

Successful XML Response


	
	
	

Failed XML Request


	
	
	

Failed XML Response


	
	
	

Failed Notification Sample


	

eKonto

eKonto is one of the products offered by the Czech Republic's Raiffeisen Bank. All eKonto owners can make quick and easy online payments in 9 currencies.

Please refer to the generic REST or generic Hosted Payment Page integration.

eNets

eNets (Network for Electronic Transfers) is an online payment method provided to customers of Singapore banks. eNets accepts payments from major credit cards as well as Direct Debit (internet banking) from the major Singapore banks.

eNETS Direct Debit enables Internet Banking users to make real-time payments from their bank accounts. Customers are redirected from the merchant's webstore to eNets to select their bank for payments. After successfully logging on to their respective bank's internet banking system, the customer is prompted to authorize the transaction.

eNets facilitates the buying process and provides merchants with a guarantee for payment, as it is not possible to cancel any electronic payments made.

Please refer to the generic REST or generic Hosted Payment Page integration.

EPS

EPS (electronic payment standard) is an online payment method provided to customers of Austrian banks. eps online payment utilizes the established online banking systems of nearly all Austrian banks. EPS is one of the most popular means of payment for online shopping in Austria.

Customers are redirected from the merchant's webstore to the online banking window of their bank, right after selecting it. After successfully logging on to their respective account using account number and PIN, all relevant purchase data is uploaded from the shopping cart to the electronic payment system. Now all the buyer needs to do is authorize the transaction using a TAN. This procedure saves customers the time-consuming and error-prone filling in of electronic payment forms.

EPS facilitates the buying process and provides merchants with a guarantee for payment, as it is not possible to cancel any electronic payments made with eps..

Please refer to the generic REST or generic Hosted Payment Page integration.

Euteller

Euteller's payment service enables an additional online payment method to credit cards, addressing consumer security and privacy issues by placing the payment authentication responsibility with their existing online banking relationship. Consumers make instant payments using their online bank account without disclosing any personal information. Payments are processed immediately allowing merchants to receive real-time notification of payment.

Please refer to the generic REST or generic Hosted Payment Page integration.

FPX

FPX is a convenient and secure online payment solution that allows real-time debiting of a customer's internet banking account of multiple banks. It also allows immediate and direct crediting into the merchant's account by the banks.

Customers are redirected from the merchant's webstore to FPX to select their bank for payments. Customers log in to their respective bank's internet banking system with the same security credentials to authorize the payment.

Payments are conducted real-time online, thus merchants are assured of payment. A notification to confirm payment is also provided to both customers and merchants.

Please refer to the generic REST or generic Hosted Payment Page integration.

Giropay

Giropay is a payment method for online shoppers who keep a German online banking account with one of the giropay member banks. Upon entering the routing number of their bank, customers are redirected from the merchant's webstore to their bank's online banking service. After successfully logging on to their respective account using account number and PIN, all relevant purchase data is uploaded from the shopping cart to the electronic payment system. Now all the buyer needs to do is authorize the transaction using a TAN.

This procedure saves customers the time-consuming and error-prone filling in of electronic payment forms. It facilitates the buying process and – in addition to highest security standards – provides merchants with a guarantee of payment for up to EUR 10,000 per payment. giropay complements direct debit and credit card payments. This method makes new customer potential and secure payment processing available to merchants. giropay was created by a consortium comprised of Postbank, the savings banks financial group and the co-operative Raiffeisen banks. In addition, the MLP bank, Cronbank, readybank and several PSD banks participate in the giropay scheme. All online banking customers of these banks can pay automatically using giropay

Please refer to the generic REST or generic Hosted Payment Page integration.

iDEAL

iDEAL has been a payment method for shopping online in the Netherlands since 2006. It utilizes the established online banking systems of Dutch banks such as ABN AMRO, Fortis, Postbank, Rabobank and SNS Bank.

The online banking payment method iDEAL is currently the most popular means of payment for e-commerce in the Netherlands. Customers are redirected from the merchant's webstore to the online banking window of their bank, right after selecting it. After successfully logging on to their respective account using account number and PIN, all relevant purchase data is uploaded from the shopping cart to the electronic payment system. Now all the buyer needs to do is authorize the transaction using a TAN.

This procedure saves customers the time-consuming and error-prone filling in of electronic payment forms. This facilitates the buying process, exhibits security of the highest standard and provides merchants with a guarantee of payment, as it is not possible to cancel any payments made using iDEAL. Offering iDEAL to customers can open up an additional customer segment in the Netherlands – this is especially true of customers who do not own a credit card.

Please refer to the generic REST or generic Hosted Payment Page integration.

iDEAL Participating Banks

Masterpass

MasterPass is a digital wallet for faster, safer shopping, allowing customers to make purchases without entering shipping and credit card information on the merchant's website as MasterPass stores the credit card and shipping details on behalf of the customer.
The customer selects MasterPass as the payment option and is redirected to Masterpass to select the shipping and credit card information.

Masterpass Standard Checkout

The Hosted Payment Page integration allows merchants ease of integration as the Payment Gateway manages all interactions with MasterPass and is most applicable for the Standard Checkout flow.

The customer is redirected to MasterPass website to login and select the preferred credit card for payment.
The Payment Gateway will receive the credit card information from MasterPass and proceed with payment authorization with the acquirer. Once the final status of the payment authorization from the acquirer is obtained, the status will be communicated to the merchant via the Notification-URL that is configured in the merchant account. If no Notification-URL is configured in the merchant account the notification will be sent via email to the merchant in case the email address has been configured.
In addition to the notification, the merchants will receive a real-time redirect back to the merchants' website with signature for validation.

If the notification is not received by the timeout period, the merchant can request the status of the transaction by sending a Query by Transaction ID or Query by Request ID.

HPP Fields

Please refer to Hosted Payment Page integration.

The REST integration allows merchants greater flexibility and control over handling the customer experience. The merchant displays the Masterpass lightbox for the customer to sign in. After signing in, the customer is redirected briefly to the Payment Gateway which retrieves the card and shipping information before redirecting the customer back to the merchant's website.

Masterpass Express Checkout

The REST integration allows merchants greater flexibility and control over handling customer interaction but requires a higher degree of integration with the Payment Gateway and with Masterpass. With this integration, the merchant is able to obtain the preferred shipping address from MasterPass, calculate the shipping and final total amount before the final payment authorization.

At the merchant's website, the customer indicates that Pairing (allowing merchant to link account with MasterPass account) is allowed. The customer is then redirected to MasterPass website to login, select preferred shipping and credit card information for payment and also approve the pairing.
The customer is then redirected back to the merchant's website where the selected credit card information and final total amount is displayed. On order confirmation, the merchant submits the payment authorization request to the acquirer via the Payment Gateway.

Masterpass Express Checkout is a feature that requires MasterCard to approve the merchant's account. Please refer to your MasterCard account manager for more information.

The following section focuses on the Masterpass Express Checkout flows via REST API.

Standard Checkout

The merchant website displays the payment options to the customer. If MasterPass is selected, the interaction is as follows

  • REQUEST-CHECKOUT | Submits a request-checkout transaction with request-type=checkout. This informs the Payment Gateway to submit the necessary requests to MasterPass to prepare for a MasterPass checkout. Payment Gateway responds with the information required for initiating MasterPass Lightbox.
  • MasterPass Lightbox initiation | Merchant website initiates the MasterPass Lightbox with the response parameters from the request-checkout transaction.
  • Customer logs in to MasterPass, selects preferred shipping and credit card information.
  • MasterPass redirects to Payment Gateway and customer is redirected to the URL provided by merchant in the MasterPass Lightbox initiation.
  • Notification | The Payment Gateway receives the checkout updates from MasterPass and proceeds with the necessary requests to MasterPass to complete the MasterPass checkout. On completion of the steps, the Payment Gateway proceeds to send a notification to update the merchant of the completion.
  • Merchant website re-calculates the shipping amount and final amount (if necessary) and displays the masked credit card information for the customer's confirmation.
  • On customer confirmation, the merchant website proceeds with the payment authorization per normal flow.

Pairing and Checkout (First initialization)

The merchant website displays the payment options to the customer. If MasterPass is selected, the merchant website provides the customer the option to pair their account with the customer's MasterPass account. Once the customer initiates the pairing, the subsequent interaction is as follows

  • REQUEST-CHECKOUT | Submits a request-checkout transaction with request-type=pairing-and-checkout. This informs the Payment Gateway to submit the necessary requests to MasterPass to prepare for a MasterPass checkout and pairing. Payment Gateway responds with the information required for initiating MasterPass Lightbox.
  • MasterPass Lightbox initiation | Merchant website initiates the MasterPass Lightbox with the response parameters from the request-checkout transaction.
  • Customer logs in to MasterPass, selects preferred shipping and credit card information, approves pairing request from merchant.
  • MasterPass redirects to Payment Gateway and customer is redirected to the URL provided by merchant in the MasterPass Lightbox initiation.
  • Notification | The Payment Gateway receives the pairing and checkout updates from MasterPass and proceeds with the necessary requests to MasterPass to complete the MasterPass pairing and checkout. On completion of the steps, the Payment Gateway proceeds to send a notification to update the merchant of the completion.
  • Merchant website re-calculates the shipping amount and final amount (if necessary) and displays the masked credit card information for the customer's confirmation.
  • On customer confirmation, the merchant website proceeds with the payment authorization per normal flow.

Pairing Only (First initialization)

The merchant website displays MasterPass logo and option to pair. Once this is initiated, the subsequent interaction is as follows

  • REQUEST-CHECKOUT | Submits a request-checkout transaction with request-type=pairing. This informs the Payment Gateway to submit the necessary requests to MasterPass to prepare for a MasterPass pairing. Payment Gateway responds with the information required for initiating MasterPass Lightbox.
  • MasterPass Lightbox initiation | Merchant website initiates the MasterPass Lightbox with the response parameters from the request-checkout transaction.
  • Customer logs in to MasterPass, approves pairing request from merchant.
  • MasterPass redirects to Payment Gateway and customer is redirected to the URL provided by merchant in the MasterPass Lightbox initiation.
  • Notification | The Payment Gateway receives the pairing updates from MasterPass and proceeds with the necesary requests to MasterPass to complete the MasterPass pairing. On completion of the steps, the Payment Gateway proceeds to send a notification to update the merchant of the pairing status.
  • On receipt of Payment Gateway notification, the merchant proceeds to update the customer's account with the pairing status and to display the results page to the customer.

Express Checkout (Subsequent transactions)

Once a customer's account has been approved for pairing by MasterPass, the merchant can request for precheckout information prior to the payment process to allow the customer to select the preferred shipping and credit card information.

  • PRECHECKOUT | Submits a precheckout transaction with request-type=precheckout. This informs the Payment Gateway to submit the necessary requests for precheckout information to MasterPass. Please note: An express-checkout request has to be initiated within 30 mins for the precheckout request to remain valid.
  • The Payment Gateway will return MasterPass's precheckout information to the merchant. The precheckout information contains the masked credit card information and shipping information the customer has registered with Masterpass. Masterpass indicates the customer's default preferred shipping and credit card profiles.
  • The merchant's website displays the precheckout information for the customer to select.
  • Once the customer has selected the preferred shipping and credit card information for the payment, the merchant's website calculates the shipping and final amount (if necessary).
  • REQUEST-CHECKOUT | Submits a request-checkout transaction with request-type=express-checkout. This informs the Payment Gateway to submit the necessary requests to MasterPass to prepare for a MasterPass express checkout.
  • MasterPass processes the express checkout request and returns Payment Gateway the shipping and full credit card information.
  • Payment Gateway proceeds to respond to merchant with the tokenized card information.
  • The merchant website proceeds with the payment authorization with 3D-Secure (optional) per normal flow.

REST Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Request Checkout Fields

Precheckout Fields

Debit Fields

REST API XML Samples

Pairing and Checkout (First initialization)

Request


	
	
	

Response


	
	
	

Notification


		

	

Pairing and Checkout Lightbox initiation

Initialize MasterPass lightbox with the following script in the origin_url page


	

	

Pairing (First initialization)

Request


	
	
	

Response


	
	
	

Notification


	

	

Pairing Lightbox initiation

Initialize MasterPass lightbox with the following script in the origin_url page


	

	

Precheckout (Subsequent transactions)

Precheckout Request


	
	
	

Precheckout Response


	

	

Express Checkout (Subsequent transactions)

Express Checkout Request


	
	
	

Express Checkout Response


	

	

Debit (After Pairing and Checkout / Express Checkout)

Debit Request


	
	
	

Debit Response


	

Maybank2u

Maybank2u.com is a product offered by Maybank. As one of the major banking groups in Asia, Maybank allows customers to pay for online purchases directly from their bank accounts.

Please refer to the generic REST or generic Hosted Payment Page integration.

Moneta ru

Moneta.ru is a payment system, offering safe and instant online transactions. Using Moneta.ru, you can send and receive payments to your e-wallet.

Please refer to the generic REST or generic Hosted Payment Page integration.

PayPal

PayPal Express Checkout is a service that allows customers to pay using a PayPal account instead of a credit card. Customers can make purchases without entering billing, shipping, and credit card information as the information is already stored with PayPal. Merchants should provide details about the order so that the order information can be displayed to the customer during the PayPal checkout process.

The customer is able to change the shipping address within the checkout in PayPal. Therefore the account holder and shipping information together with other payment details are returned to merchant's web shop for further processing on successful transaction completion.

PayPal supports debit, authorization and capture, void, refund and authorization-only transactions (please see Transaction Types for details).

Following the Alternative Payments flow,

  1. The payment-method-url to the PayPal Express Checkout Landing-Page will be sent in the response if the request is successful.
  2. A notification will be sent to the merchant as a final status of the payment once the Payment Gateway receives it from the PayPal.

Once the Payment Gateway has received a notification from PayPal about the final status of the transaction, this status will be communicated to the merchant via the Notification-URL that is configured in the merchant account. If no Notification-URL is configured in the merchant account the notification will be sent via email to the merchant in case the email address has been configured.

For HPP integration, in addition to the notification, the merchants will receive a real-time redirect back to the merchants' website with signature for validation.

If the notification is not received by the timeout period, the merchant can request the status of the transaction by sending a Query by Transaction ID or Query by Request ID.

HPP Fields

Please refer to Hosted Payment Page integration.

REST Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

Please note: Order item details may be sent along with transaction requests. This information of the shopping basket will be displayed in PayPal during the checkout and later stored as a part of the payment details in PayPal. However, they cannot be obtained from the Payment Gateway later as part of transaction details.

Reference transactions

Reference transactions are transactions that are related to a parent transaction.

  • CAPTURE-AUTHORIZATION | Available only on successful AUTHORIZATION which is not voided nor fully captured. Partial and multiple captures are allowed, provided the authorization limit is not exceeded.
  • VOID-AUTHORIZATION | Available only on successful AUTHORIZATION which is not voided nor captured. Authorization can only be voided as a whole.
  • REFUND-DEBIT | Available on successful DEBIT. Partial and multiple refunds are allowed, provided the original amount is not exceeded.
  • REFUND-CAPTURE | Available on successful CAPTURE-AUTHORIZATION. Partial and multiple refunds are allowed, provided the original amount is not exceeded.

Recurring transactions

To submit a recurring transaction, the merchant must first submit a request with the transaction-type DEBIT, AUTHORIZATION or AUTHORIZATION-ONLY and also include the periodic-type element with values "recurring" or "installment". Additionally, the sub-element sequence-type with one of the following values must be submitted:

  • first: The first transaction in a series of recurring transactions
  • recurring: A transaction that is part of a series of recurring transactions.
  • final: The final transaction in a series of recurring transactions. A payment with this sequence-type completes a chain of recurring payments.

An AUTHORIZATION-ONLY transaction can only be the first one in the series, and the amount must be zero. It effectively creates a valid Billing Agreement ID with PayPal, without charging the customer (unlike AUTHORIZATION or DEBIT).

The periodic-type element is intended as differentiation for the merchant's use. Which of the two periodic-type is chosen depends on the merchant's business model. "installment": indicates one in a set that completes a financial transaction and "recurring": indicates one in a set that occurs repeatedly, such as a subscription. Both "recurring" and "installment" transactions will be processed the same way.

"recurring" and "final" transactions need to reference (via parent-transaction-id) a valid "first" transaction. When a transaction with sequence-type "final" has been submitted, it is not possible to submit another "recurring" or "final" transaction for this series.

Only one periodic-type may be used for the complete series of recurring payments (ie. the periodic-type in a subsequent transaction must match the periodic-type sent in the "first" transaction).

Recurring transactions Fields

REST API XML Samples

For PayPal REST requests, the response to the transaction provides the payment-method-url to the PayPal Express Checkout Landing-Page. It does not indicate a completed authorization transaction.

Merchants must redirect the consumer for the authorization transaction to proceed.

Once the consumer has completed the transaction at PayPal, the Payment Gateway will be notified. With this notification, a notification will be sent to the merchant as a final status of the payment.

Successful One-time Authorization Request

Request


	
	
	

Response


	
	
	

Notification


	

	

Successful Recurring Initial Authorization Request

Request


	
	
	

Response


	
	
	

Notification


	

	

Successful Recurring Subsequent Authorization Request

Request


	
	
	

Response


	
	

POLi

POLi is an online payment option that offers a great alternative to credit cards. POLi provides a seamless and secure payment experience by directing customer's payment to the merchant's account. Customers login to their bank, selects their preferred account and confirms the payment. Customers will receive an immediate confirmation of their POLi payment while merchants get instant payment notification.

Please refer to the generic REST or generic Hosted Payment Page integration.

Przelewy24

Przelewy24 offers its Customers various payment methods, accepts customers' payments to its account, confirms payment processing to the Seller and transfers these payments to the Seller's account. The Service transfers payments collected from Customers to the Seller's account instantaneously or at the moment of exceeding a defined amount as well as on demand.

Please refer to the generic REST or generic Hosted Payment Page integration.

Skrill Wallet

Using the payment method Skrill Wallet the end-customer can also choose another payment method within Skrill e.g. in case the wallet has not enough balance to pay the goods or services. In this case debit returns can occur (e.g. if the end customer chooses credit card or direct debit as prefered payment method). This debit-return will be sent from Payment Gateway to the merchant within an additional notification.

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

REST API XML Samples

Successful XML Request


	
	
	

Successful XML Response


	
	
	

Successful Notification

	
	

Sofort

Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

REST API XML Samples

Successful XML Request


	
	
	

Successful XML Response


	
	
	

Failed XML Request


	
	
	

Failed XML Response


	
	
	

Successful Notification


	
	
	

Failed Notification

	
	

Tenpay

Tenpay Cross-border online payment is a real-time payment solution to help chinese consumers complete transaction in overseas website. For trading convenience, whether the commodity overseas merchant provides priced in foreign currency or RMB. Tenpay can deduct the payment from the buyers' account in RMB real-time and settle with merchant in foreign currency.

Please refer to the generic REST or generic Hosted Payment Page integration.

Transaction Flow

Tenpay Transaction Flow

Trustly

Customers find the Trustly payment method easy to use, while retailers find it secure. Based on the cross-border cooperation between a series of national banks, Trustly is open to all customers holding bank accounts in any of the supporting countries.

Please refer to the generic REST or generic Hosted Payment Page integration.

UPOP

UnionPay Online Payments (UPOP) is the payment method, provided by UnionPay, for their cardholders to use when making purchases online. UPOP provides a safe and secure shopping environment for UnionPay cardholders and is supported by over 50 Chinese Financial Institutions that issue UnionPay cards.

Please refer to the generic REST or generic Hosted Payment Page integration.

Transaction Flow

Tenpay Transaction Flow

UPOP Express Pay

UnionPay Online Payments (UPOP) Express Pay enables processing of cards without redirecting the consumer to UPOP as seen in the standard UPOP integration.

Please refer to the generic REST or generic Hosted Payment Page integration.

Transaction Flow

Tenpay Transaction Flow

Visa Checkout

Visa Checkout is a digital wallet which offers a secure and trusted environment for cardholders to store their card and personal details, and an enhanced online shopping experience for registered cardholders.

Hosted Payment Page Implementation

The Hosted Payment Page integration allows merchants ease of integration as the Payment Gateway manages all interactions with Visa Checkout.

The customer is redirected to Visa Checkout website to login and select the preferred credit card for payment. The Payment Gateway will receive the credit card information from Visa Checkout and proceed with payment authorization with the acquirer. Once the final status of the payment authorization from the acquirer is obtained, the status will be communicated to the merchant via the Notification-URL that is configured in the merchant account. If no Notification-URL is configured in the merchant account the notification will be sent via email to the merchant in case the email address has been configured. In addition to the notification, the merchants will receive a real-time redirect back to the merchants' website with signature for validation.

If the notification is not received by the timeout period, the merchant can request the status of the transaction by sending a Query by Transaction ID or Query by Request ID.

HPP Fields

Please refer to Hosted Payment Page integration.

REST Implementation using Payment Gateway redirect

The REST Implementation using Payment Gateway redirect is a hybrid of HPP and pure REST API.

In this integration, the merchant hosts the payment page and checks with the customer on the preferred payment method. The customer selects Visa Checkout and the merchant sends a REST request to Payment Gateway. Payment Gateway returns URL for redirection and handles the lightbox initialization and all integration to Visa Checkout.

The merchant website displays the payment options to the customer. If Visa Checkout is selected, the subsequent interaction is as follows

  • Submits a debit / authorization / authorization-only / get-url transaction to the Payment Gateway. This informs the Payment Gateway to prepare the Visa Checkout URL for redirect. Payment Gateway responds with the URL required to redirect customers.
  • Visa Checkout Lightbox initiation | Merchant website redirects customers to Payment Gateway's URL. Visa Checkout light box is initiated.
  • Customer logs in to Visa Checkout, selects preferred credit card information.
  • Visa Checkout redirects to Payment Gateway and customer is redirected to the Payment Gateway. Payment Gateway proceeds with the necessary requests to Visa Checkout to obtain the credit card information. Payment Gateway processes the payment request (if required) before redirecting the customer to the merchant's website.
  • Notification | On completion of the request, the Payment Gateway proceeds to send a notification to update the merchant of the completion.

REST Implementation

The full REST Implementation allows merchants to implement a pure server-to-server call with Visa Checkout and Payment Gateway.

In this integration, the merchant hosts the payment page, checks with the customer on the preferred payment method and handles the lightbox initialization to Visa Checkout. Payment Gateway handles the retrieval of credit card information from Visa Checkout so that the merchant does not have to handle PCI sensitive information.
Merchant handles the request calls with Visa Checkout and submits the Visa Checkout callId via the wallet/request-token field to Payment Gateway for payments processing.

The merchant website displays the payment options to the customer. If Visa Checkout is selected, the merchant website will integrate to Visa Checkout. On obtaining the payment/data/{callId} from Visa Checkout, the subsequent interaction is as follows

  • Submits a check-enrollment / debit / authorization / authorization-only transaction to the Payment Gateway with callId provided in the wallet/request-token field.
  • Payment Gateway handles the necessary requests to Visa Checkout to obtain the credit card information before proceeding with the payment request processing.
  • Notification | On completion of the request, the Payment Gateway proceeds to send a notification to update the merchant of the completion.

REST Fields

Please refer to Payment Fields for a full list of fields. Only the fields listed below have differing Cardinality.

REST Implementation

REST API XML Samples

REST Implementation using Payment Gateway redirect

Request


	
	
	

Response


	
	
	

Notification


	

	

REST Implementation

Request


	
	
	

Response


	
	
	

Notification


	

Yandex Money

Yandex.Money is the largest online payment service in Russia. We make shopping at online stores accessible for all Russians. The service also allows users to conveniently pay for services, like home utilities and mobile phone.

Please refer to the generic REST or generic Hosted Payment Page integration.

Yapital

With Yapital, you can shop online as usual and pay quickly, easily and safely. At checkout, consumers scan the displayed Yapital QR code with the Yapital mobile app.

Please refer to the generic REST or generic Hosted Payment Page integration.

Credit Card Batch Processing

Credit Card Batch Processing specification is intended to be read by the technical staff in the merchant's organization responsible for integating to Credit Card Batch Processing, a secure solution that is designed to help merchants submit batches containing multiple transactions.

Workflow

Workflow
  1. The Merchant Operator applies PGP encryption using the Payment Gateway's Public Key and uploads the encrypted Request File via SFTP (in folder).
  2. The Batch Processing Service retrieves the Request File and moves it the inprogress folder.
  3. The Batch Processing Service processes each transaction in the Request File and generates a PGP encrypted Response File using the Merchant's Public Key.
  4. The encrypted Response File is deposited in the out folder on the SFTP server. The original Request File is moved to the .done folder.
  5. The Merchant Operator retrieves the encrypted Response File and decrypts it using their private key.

PGP Encryption

Pretty Good Privacy (PGP) is a data encryption and decryption computer program that provides cryptographic privacy and authentication for data communication. PGP encryption uses a serial combination of hashing, data compression, symmetric-key cryptography, and, finally, public-key cryptography; each step uses one of several supported algorithms. Each public key is bound to a user name and/or an e-mail address.

Please refer to http://www.pgpi.org/doc/pgpintro/ for more information on PGP.

Linux Command Line Samples

Create Key
gpg --gen-key

Import Key
gpg --import batch-user.pub

Export Public Key
gpg --armour --export batch-sandbox > /root/batch-sandbox-pub-key.asc

Encrypt File
gpg -e -r "batch-user" batch-request.csv

Decrypt File
gpg -d batch-response.csv.gpg

Windows Samples

Please visit http://www.gpg4win.org/ for client and samples of PGP encryption on Windows.

Public Key Exchange

Since the Public-Key Infrastructure (PKI) is used for all message exchanges, it is neccesary that public keys are exchanged between platforms prior to integration.

Public Key Exchange

Sandbox Public Key

The sandbox public key is listed below. This public key is used for encryption of the Batch Processing Request File. You can download here.


-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2.0.14 (GNU/Linux)

mQENBFFTazIBCACsu4VCFtb1nEWmhBcG2rCjuprOqdEycm9T+lntqMKK/HmcM4NC
ElY3dEg46ltqnnlRPF+3w0rYNG+h5xwlBR1FgH9aqGQNt7vRBJjtbRmoA1z1NXXV
ztVgvjWsAinEodiueii55MwEQmNoF7v06zsbHcEGiBuuq48vyr5OKRhC0dpckx3P
EawrZ2OSpYpEtPT6hvuE4uikIMe4K/3d2ZmM8TLS8jqnNDEC2+bBWd4SKF3fbqUM
a3SfwXe1UGrfmhcIf5ETXZSfKEsAS+OzOeg2AkzFjYvEcS5dwKVCRL6hYovEWicL
akh2G6f669bywyiZslbZJg5ZHzRSYIdRxkYvABEBAAG0cXNhbmRib3gtYmF0Y2hp
bmctcHVibGljLWtleSAoU2FuZGJveCBiYXRjaGluZyBmaWxlIGVuY3J5cHRpb24g
a2V5KSA8c2FuZGJveC1iYXRjaGluZy1zdXBwb3J0QGVsYXN0aWNwYXltZW50cy5j
b20+iQE+BBMBAgAoBQJRU2syAhsDBQkSzAMABgsJCAcDAgYVCAIJCgsEFgIDAQIe
AQIXgAAKCRDY4NvfKBdE/b56B/9scSMsLEUqKxDr/BKiHtfpr9bEva0MCehVHYgJ
m3uOVPPcF6WZ8LSQa89GYDiZfs6tZpb1KWaiLnOgY0WXiTAQH9oa0zbqUHInV32y
3IZ19N1lBFoJSUztLYI0llnfMRlNFoxtBtA6aRtvXBKci9nc2UVR2I+5vqRlse34
ZGYndvJx6AFCLqgBv25PItJzBz8Hs/2vS6VQ5qWCmI70px2OSGxB7M9X995o+x/I
18RIBtnNaPQSkTvi5/ywhuSCDC11iEbOc8iLrdHRsDYaL0ouqUStIRxCh0Cx0Oy5
kd2uzM2S4mzm0zO7MoNDP2H1Hf7EaksY8uFLzwih798ted2ouQENBFFTazIBCACk
mznaDawkj/srpNbmomG0UXPJSFsZLUP/yyCKUdZCulm+uQhTEV39CTuvENhRfOrQ
C8sDqauikbumQ8rqaeADVfv43YRK2QIXO/oP8aucnE8GneJGW8YCxVVfREzNNJrM
sbQznjiagtUpnLVIFtRLNpwRNt91CzsUB7Uv3kFCj0aAWFyr+v1llNQe+NoNdpW4
qm8Gm1dpHYycImG7sRsAINdXbgSeg5XnIzqzV1vbijG12X2ATq950bPBytTNr8jD
opf+OzPH3lC5mhcX8+8cpokQqJTRKV8ZTQHtaIX7vW4AbKcG7l04SDA2uyLdm9K/
80uJvnI5RKLIGTdkG6yDABEBAAGJASUEGAECAA8FAlFTazICGwwFCRLMAwAACgkQ
2ODb3ygXRP3seQf/Rxxm+ymeXMBSgQ8Zdj7WOveqMVtPvMzbq2tXZp2UT8wO6yhB
J88FzdnPQfTOeJq46HsYpKmja0V3+gYbVXmJkLO8ZT0lYu+euhLVvTDE1RThvCuH
IjLxsTjogeuvtnDbT/s/khu032d131qGs+dHP2LRuyQxJM3Kp1AAoSf4UQzPGZiC
VfgDRrhNAyVGrl8xutoVbCOTtWJbdXbC0piqHuqnGGbshHs9sce7NI++M4K4TxdY
xiWVhF5niJ50evGyCAm47X7uJHk6/EVwSAbAlbAbhkFzweLcu+7uCrfbIln/nGfE
frjJ9jGq5CLZJjc00EtkNB65wacQHxzfq7EU2w==
=MPTt
-----END PGP PUBLIC KEY BLOCK-----

Production Public Key

The production public key will be provided prior to production integration.

Merchant Public Key

The Merchant is required to send their public key via email to their Technical Support Representative. The Merchant's Public Key is used for encryption of the Batch Processing Response File.

SFTP

SFTP is used to securely transfer files between the merchant and the Batch Processing Service.

Folder Structure

.done
The folder where Request Files are stored once processing has completed.

in
The folder where the Merchant Operator uploads the encrypted Request File.

inprogress
The folder where currently processing Request Files are stored.

out
The folder where Response Files are stored.

URL and Credentials

The URL and credentials for the SFTP Server will be provided prior to integration. Please contact technical support if you have not received your credentials.

File Specifications

Request and Response files must be:

  • Encrypted with PGP
  • Formatted as CSV (Comma Separated Values)
  • Qualified using double quotes i.e. "John","Doe" for all fields.
  • Include header columns for each field.
  • Encoded in UTF-8

Request File Naming

Request file names must be unique and in the following format:
requestbatchid.timestamp.request.csv.gpg

For example: batchsample001.20120101180130.request.csv.gpg

Where timestamp is in the format of YYYYMMDDhhmmss and in UTC timezone.
The Request Batch ID will be included in the Response Filename and within the Response File content.
The entire filename will be included in the Response Filename and within the Response File content.

The Request Batch ID is limited to a maximum of 64 characters and should not contain any special characters.
The Batch Alias can be used as a simplified identifier for the merchant.

Request File Format

Please refer to File Samples for a sample file

Response File Naming

Response files are in the following format:

Response files will be named after the Request file including the Request Batch ID and timestamp.
requestbatchid.timestamp.response.csv.gpg

For example, a Request file named:
batchsample001.201201011801.request.csv.gpg

The corresponding Response file will be named:
batchsample001.201201011801.response.csv.gpg

Response File Format

Please refer to File Samples for a sample file

File Samples

download sample request file
download sample response file

Transaction Reconciliation

This specification is intended for merchants matching their transaction response messages with data report files stored on the Payment Gateway.

To be able to download the data report files the IP address of the merchant server connecting is required to be whitelisted in the Payment Gateway firewall.

What is Reconciliation?

The purpose of reconciliation is to compare transaction records and verify that payments have been processed correctly. By reconciling transaction information regularly, merchants will gain a better understanding of their business transaction life cycle - from initial authorization, to settlements, transaction disputes (chargebacks), refunds or reversals.

Reconciliation Files

The Payment Gateway generates transaction reports which are very similar to typical bank account statement. Merchants are recommended to match and reconcile these report files regularly (daily) with the data recorded on their system. When matching transaction data it is important to remember how the payment total is calculated and also that the data does not represent a complete payment history but only the account activities that have been recorded over the previous 24 hours.

Reconciliation Process

The reconciliation files must be downloaded from an SFTP server on the Payment Gateway platform. Although it is possible to download files manually it is recommended to automate the process for the sake of consistency and convenience. Likewise, it is recommended to run a program to facilitate the reconciliation process of the downloaded files. The program used must be able to handle the CSV file format described further below.

To reconcile your transactions simple compare transactions in the reconciliation file with the transaction data on your record. Should you remark inexplicable discrepancies between the reconciled data and your records which you cannot resolve internally, please contact your support representative.

File Specifications

The system is configured to generate transaction reports containing sequential datasets for each of your transaction requests processed by the system. These records are called reconciliation files and are saved in CSV format on the SFTP server. When opened and read in a spreadsheet application like Microsoft Excel, the data entries are divided in columns and rows. Opened as plain text in any standard text editor program, however, the field entries are separated by a semicolon (;).

The files contain transaction data processed over a specified period of time, normally 24 hours. They do not present a complete payment flow per card (from authorization, to settlement with possible rejections and disputes) but only those transactions which have been processed by the Payment Gateway within the time period for which the report has been created.

Naming Convention

The reconciliation files are stored on the SFTP server in the following format: mr_[Identifier]_[From_Completed_On]_[To_Completed_On].csv

where:

  • ‘mr' is a prefix identifying the Merchant Reconciliation file
  • [Identifier] is a name for the group of merchant account id's being represented in the file.
  • [From_Completed_On]: The start of the time period that this file covers, in "Transaction Completed Time", in the format YYYYMMDDHH.
  • [To_Completed_On]: The start of the time period that this file covers, in "Transaction Completed Time", in the format YYYYMMDDHH.
  • .csv is the file extension denoting the format Character Separated Value

Typical Example:
mr_WIDGETCO_2013050100_2013050200.csv

This file can be read as a "Merchant Reconciliation File" for the company "WIDGETCO" spanning a time period from "May 1, 2013 00:00" to "May 2, 2013 00:00".

Custom Example:
mr_WIDGETCO_2013050103_2013050203.csv

This file can be read as a "Merchant Reconciliation File" for the company "WIDGETCO" spanning a time period from "May 1, 2013 03:00" to "May 2, 2013 03:00". The custom example is simply there to show a file that can be configured to a different start and end time

File Format

The report file mr*.csv lists all transactions processed over a certain period of time. The data is recorded in the following columns and fields.

To ease the introduction of additional columns in the future, reserved fields were introduced. These fields will be used to include additional information in the reconciliation file in the future. By using reserved fields in the future no or minimum adaption of merchant systems should be necessary.

File Samples

download sample reconciliation file

Help and Support

FAQ

REST API Integration

Question: "We are receiving the following response when trying to process a transaction: <status code="400.1048" description="This Merchant Account does not have a Provider Account associated with it. Please contact technical support." severity="error"/>"

You are passing a payment method, card type, or currency that is not properly configured on your merchant account. Please contact your PSP to doublecheck your merchant account setup.


Question: "We keep receiving duplicate request id errors: <status code="400.1018" description="The same Request Id for the Merchant Account is being tried a second time. Please use another Request Id. " severity="error"/>"

The <request-id> element must be unique for every transaction. If the problem persists, please contact technical support as it can also be an indication of a technical error.


Question: "When submitting and/or querying transactions, I'm getting this HTML response back but would like it to be in xml format:
HTTP/1.1 201 Created
Server: nginx/1.0.14
Date: Mon, 06 Aug 2012 05:23:58 GMT
Content-Type: text/html;charset=UTF-8
Connection: close
Content-Length: 2299
Set-Cookie: JSESSIONID=E46B646F5537821830F7DB1EFE5D77F8; Path=/engine
Content-Language: en-US
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"... "http://www.w3.org/TR/html4/loose.dtd">
<html>
        <head>
                <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
                <title>Transaction Details</title>
                <style type="text/css">
                        table {border-collapse: collapse; font-family: verdana; font size: 11px; margin: 0 auto;}
                        th {background-color: #ddd; padding: 5px; font-size: 13px;}
                        td {padding: 5px;}
                        td.label {background-color: #eee; font-weight: 900;}
                </style>
        </head>
        <body>
                <table border="1">
                        <tr><th colspan="2"><b>Transaction Details</b></th></tr>
                        <tr><td class="label">Transaction Identifier</td><td>ebe10c14-df86-11e1-958e-0019b9f1412f</td></tr>
...						

Please ensure you're setting the HTTP Content-Type Header to "application/xml" in your request.

Content-Type: application/xml


Question: "Where do I put my username & password when sending a transaction?"

Authentication is done via Basic HTTP authentication. See http://en.wikipedia.org/wiki/Basic_access_authentication#Protocol for more information


Question: "My REST transaction query is producing an empty response."

Please doublecheck the merchant-account-id you are using. In addition, you must supply a valid request-id that references a submitted transaction.

Question: "How can I submit a successful recurring Authorization request?"

There are 2 ways to perform recurring transactions:

  1. By using referenced-authorization or referenced-purchase transaction type for subsequent/recurring transaction:
    REQUEST
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <payment xmlns="http://www.elastic-payments.com/schema/payment">
        <merchant-account-id>c9cbc1f0-be3a-4264-8395-450c94d4d836</merchant-account-id>
        <request-id>f332158b-a2f7-4067-ad66-b430fdfd4228</request-id>
        <transaction-type>referenced-authorization</transaction-type>
        <parent-transaction-id>48ff1d5f-9652-11e2-9b9e-00163e7f9842</parent-transaction-id>
        <requested-amount currency="USD">10.00</requested-amount>
        <ip-address>127.0.0.1</ip-address>
    </payment>
    
    RESPONSE
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <payment>
      <merchant-account-id>c9cbc1f0-be3a-4264-8395-450c94d4d836</merchant-account-id>
      <transaction-id>4b37efd8-9652-11e2-9b9e-00163e7f9842</transaction-id>
      <request-id>f332158b-a2f7-4067-ad66-b430fdfd4228</request-id>
      <transaction-type>referenced-authorization</transaction-type>
      <transaction-state>success</transaction-state>
      <completion-time-stamp>2013-03-26T20:18:16.904Z</completion-time-stamp>
      <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
      </statuses>
      <requested-amount currency="USD">10.00</requested-amount>
      <card-token>
        <token-id>4557271468161111</token-id>
        <masked-account-number>444433******1111</masked-account-number>
      </card-token>
      <ip-address>127.0.0.1</ip-address>
      <payment-methods>
        <payment-method name="creditcard"/>
      </payment-methods>
      <authorization-code>153620</authorization-code>
    </payment>
    
    
  2. By leveraging the token information from the initial transaction response to do subsequent recurring transaction
    REQUEST
    <payment xmlns="http://www.elastic-payments.com/schema/payment">
       <merchant-account-id>c9cbc1f0-be3a-4264-8395-450c94d4d836</merchant-account-id>
       <request-id>28570960-09c6-41b6-bc37-bad59f40ba6e</request-id>
       <transaction-type>authorization</transaction-type>
       <requested-amount currency="USD">2.00</requested-amount>
       <account-holder>
          <first-name>John</first-name>
          <last-name>Doe</last-name>
       </account-holder>
       <card-token>
          <token-id>4557271468161111</token-id>
       </card-token>
       <ip-address>127.0.0.1</ip-address>
    </payment>
    
    RESPONSE
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <payment>
      <merchant-account-id>c9cbc1f0-be3a-4264-8395-450c94d4d836</merchant-account-id>
      <transaction-id>c1b4be6e-9654-11e2-9b9e-00163e7f9842</transaction-id>
      <request-id>28570960-09c6-41b6-bc37-bad59f40ba6e</request-id>
      <transaction-type>authorization</transaction-type>
      <transaction-state>success</transaction-state>
      <completion-time-stamp>2013-03-26T20:35:56.416Z</completion-time-stamp>
      <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
      </statuses>
      <requested-amount currency="USD">2.00</requested-amount>
      <card-token>
        <token-id>4557271468161111</token-id>
      </card-token>
      <ip-address>127.0.0.1</ip-address>
      <descriptor>graypay Amazon</descriptor>
      <authorization-code>153620</authorization-code>
    </payment>
    

Contact

For questions relating to this document please contact:





Phone:
Email:

Version

The current version is 1.152
and was last updated on Mar 04 2019

Reference

Payment Methods

Transaction Types

Transaction States

Card Types

Transaction Statuses

Countries

Currencies

Locales

Payment XSD