About B-Gateway
B-Gateway is a code name for a web service that allows a merchant to obtain authorizations for credit card transactions and to submit transactions for clearing and settlement.
Key features
B-Gateway’s key features enable the user to do the following:
Get authorizations – allows the user to either make a normal purchase transaction or to pre-authorize it.
The difference is:
If a transaction is pre-authorized, the given amount is reserved from the cardholder’s account. The amount will not be charged to the cardholder until a financial transaction is submitted. The authorization code needs to be stored by the merchant and later used to send in the financial transaction. Financial transactions are submitted by calling getAuthorization with the AuthCode from a previous pre-authorized transaction.
With the normal purchase transaction the cardholders account is charged for the given amount. If the transaction was pre-authorized then the transaction must include the authorization code received from that transaction.
This feature also allows the user to make a refund transaction if he wants to refund an amount to the cardholder’s account.
Cancel authorizations – allows the user to cancel previously authorized transactions. Authorizations can be cancelled if the batch they belong to is still open. If it is closed then a refund transaction must be used.
Create new batches – allows the user to create a new batch. By doing so the user closes the currently open batch and opens a new one.
Get batch authorizations – allows the user to authorize many transactions as one batch.
Get processing results – allows the user to get results from previous batch job.
Get transaction lists – allows the user to get a transaction list from the authorization service listing, on either batch or transaction level details on transactions processed through the service.
Send detail data – allows the user to supply detailed invoice after the financial transaction has been processed.
3DSecure payments
The 3DSecure procedure is a procedure where the cardholder is authenticated resulting in less chance of fraudulent transactions. 3DSecure is mandatory for ecommerce transactions in Europe.
To enable 3DSecure payments you will need to connect to a Merchant Plugin Interface (MPI), SaltPay provides a MPI to its ECommerce customers but there are also other MPI vendors available. For further information about 3DSecure see 3DSecure - B-Gateway Payments.
Introduction to batches
A batch is a unit that the acquirer uses to settle with the merchant. It is a collection of credit card transactions charged over a period of time, usually one day.
Each batch is identified by a batch number and this batch number must be unique per terminal within one year. The batch number can either be controlled by the merchant or the authorization services. This will be explained later.
How does B-Gateway work
B-Gateway will expose the authorization services with the use of web services. The web services run securely over HTTPS.
All web services provided by B-Gateway will be password protected. The connecting merchant has to supply username and password each time the merchant calls a B-Gateway web service.
Once the merchant has connected to the web service he will be able to access the features mentioned above. When using these features the merchant must send all necessary information on XML format. This will be explained later. This XML information will then be sent through the web service and a response, also on XML format, will be given.
Model 1 – This diagram shows an example of B-Gateway’s process
Data Storage and Manipulation
The security of cardholder account data has become one of the biggest issues facing the payment card industry. Visa and MasterCard have therefore created the Payment Card Industry Data Security Standard (PCI DSS) – a set of industry-wide requirements and processes, that are supported by all international payment card systems.
PCI DSS is intended for any organization that stores, transmits or processes cardholder account and transaction data – merchants, acquiringbanks and related service providers.
The PCI standard is available at https://www.pcisecuritystandards.org Please download and review the standard.
While all merchants are required to comply with thePayment Card Industry Data Security Standard, merchants that store, process or transmitcard account data may also be required to validate compliance with their acquirer. Please note that for a merchant to be considered compliant, any Service Providers that store, process or transmit card account data on behalf of the merchant must also be compliant.
Data types
Field Form
A Alphabetic
N Numeric
AN Alphanumeric
Z ISO 7811 and ISO 7813 track 2 and track 3 data format
Field Length
10 Indicates length=10
LL..19 Indicates max length of 19
..17 Variable length up to 17 characters
Field Code
M Mandatory
C Conditional
O Optional
Amounts
All amounts are represented with two digits after the decimal and an implied decimal point.
Icelandic Krona is therefore represented in aurar. Dollars are in cents etc. For instance 100
USD is in TrAmount as “10000”.
Getting authorizations
Normal purchase transaction
This element is referred as TransType 1 in the XML sheet. If you wish to make a normal purchase transaction you can either insert a variable in the AuthCode in the XML sheet or leave the field empty.
The difference is that if the AuthCode is empty B-Gateway will request authorization from the issuer and, if successful, B-Gateway will storethe financial transaction in its database and later submit the financial transaction to the acquirer automatically.
OR
If the transaction has already been authorized by the pre-authorizing element or by other channels the AuthCode will contain the auth code that was received during the preauthorization process. This is sometimes referred to as submitting financial transactions. In this case B-Gateway will store the financial transaction in its database and not request authorization from the issuer to ensure that the card account does not get reserved twice. B-Gateway will then later submit the transaction tothe acquirer automatically.
In either case the transaction number and batch number are always returned from the web service. If Transaction and Batch variables are notset in input requests they are created and returned in the response.
Refund
This element is referred as TransType 3 in the XML sheet. This transaction type is used when a merchant wants to refund an amount to a customer. If the refund is successful the response to the merchant contains the AuthCode of the reversal, as well as Transaction and Batch numbers. In other case the response contains an error code.
Partial Reversal
This element is referred as TransType 4 in the XML sheet. This transaction type lowers the amount on a currently existing sale and advices the issuer to change the cardholder’s withdrawal limit by the same amount. The transaction type can only be used on a sale created on the same day and therefore in an open batch. The message must contain the original amount, and the new amount.
If the partial reversal is successful the response to the merchant contains the AuthCode of the reversal, as well as Transaction and Batch numbers. In other case the response contains
an error code.
Pre-authorizations
This element is referred as TransType 5 in the XML sheet. This transaction type is used when the merchant wants to reserve an amount from a customer’s credit card. An Authorization Request is then sent to the acquirer. If the request was authorized the transaction is added to a system database containing the new AuthCode. Transaction and batch numbers are not assigned to the transaction as the transaction is only a pre-authorization request. The response sent to the merchant therefore only contains AuthCode, not Transaction and Batch.
Recurring Zero amount authorization
The Payment Gateway does support zero amount to be sent to verify cards for MasterCard and VISA. The only requirement is that the authorization must be a pre-authorization. This is most often used in recurring sales.
Dynamic Descriptors
DD information is sent by adding the following parameters to the authorization message.
MerchantName AN 1..22
MerchantHome AN 1..20
MerchantCity AN 1..13
MerchantZipCode AN 1..10
MerchantCountry A2, two letter country code
MerchantName must always have value and the proper way is to fill in all the parameters. If a parameter is missing then the gateway will fill out the rest with pre-configured values which might not properly represent the merchant. DD works with all authorization requests except cancelAuthorization. For pre-authorization (Transtype 5) MerchantName, MerchantCity and MerchantContry will be sent (limited by card schema regulation), for financial authorization (Transtype 1, 3, 4) all parameters are sent, that also applies when pre-authorizations arecaptured with sale (Transtype 1). For pre-authorization with capture it is recommended that the pre-authorization also contains the DD since it is a requirement from VISA, MasterCard uses the financial record.
The merchant contract numbers have to be specifically configured through business channels to allow use dynamic descriptors, if not then these parameters will be ignored.
Name, ZipCode and City can contain AlphaNumeric letters along with common characters such as *, +, - _ . While no characters are explicitly forbidden then the reality is that several issuer dislike uses of characters such as &, <, >, ?, /,. \ and they should be avoided.
All parameters must be completed and contain correct data if dynamic descriptors are to work
MasterCard has a restriction that requires home, zipcode and country to referr to an actual address.fs
See example below.
Getting authorizations - XML explanations
Table GA.1 – Field explanations for a sent XML
| Field | Length | Form | Type | Explanation |
|---|---|---|---|---|
| Version | 4 | AN | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | 7 | N | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantID | ..8 | AN | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalID | ..8 | Optional | A terminal id in B-Gateway for the merchant requesting services. Must be set if default terminal is not defined for merchant. | |
| TransType | 1 | N | Mandatory | 1 = Normal purchase transaction 3 = Refund 4 = Partial Reversal 5 = Pre-Authorize |
| TrAmount | ..12 | Mandatory | Amount, in general it includes two decimal points, i.e. 100 USD is 10000. Currently JPY is the only exception, it contains no decimal points. |
|
| NewAmount | ..12 | Mandatory | Only used by transtype 4. Contains the new amount to override the original sale amount. | |
| TrCurrency | 3 | N | Mandatory | Transaction currency ISO 4217 352 => ISK 978 => EUR |
| DateAndTime | 12 | N | Mandatory | YYMMDDhhmmss. When repeated use original date and time |
| PAN | LL..19 | N | Conditional | Card number – Used if a card number is entered manually. See also Track1/Track2. Card number can be a virtual card (see function getVirtualCard). If TransType is refund then PAN can be empty, PAN from a transaction of TransType=1 with the same DateAndTime + RRN will be used. |
| ExpDate | 4 | N | Conditional | Expiration date – YYMM not used if Track1/Track2 |
| Track1 | LL..6 | AN | Conditional | Mandatory if magnetic stripe read and not Track2 |
| Track2 | LL--37 | Z | Conditional | Mandatory if magnetic stripe read |
| RRN | 12 | AN | Mandatory | Retrieval Reference Number – Reference number for transaction. Must be exactly 12 characters. Recommended format is a fixed value followed by a sequence, for example ACME00012345. The last six letters must contain a numeric value. |
| AuthCode | ..6 | AN | Conditional | Authorization code of a previous preauthorized transaction. Include this code to use the previously gotten authorization code |
| CVC2 | 3 | N | Optional | Used in cardholder not present situations such as internet sales. Code is printed on the back of the cardholder´s card |
| SecurityLevelInd | 1 | AN | Optional | Security Level Indicator – Used with Secure Code to indicate the security level used in electronic transactions This property is mandatory in electronic commerce and is used to identify the level of security used when doing the transaction. 0 = UCAF not supported by merchant 1 = UCAF supported by merchant but not provided by issuer 2 = UCAF is present Mapping from MPI is MPI(1) 2 MPI(2,3,4) 1 MPI(5,6,7,8) 1 |
| UCAF | 32 | AN | Conditional | Universal Cardholder Authentication Field – Used with Secure Code |
| CAVV | 28 | AN | Conditional | Verified by Visa, Base64 encoded cardholder authentication verification value, f.ex AAACCRSQJ4lShoBncZAnAAAAAAA= |
| XID | 28 | AN | Conditional | Verified by Visa. The unique transaction action id identifier encode by Base64. |
| MerchantName | 1..22 | AN | Conditional | Name of merchant. |
| MerchantHome | 1..20 | AN | Conditional | Merchant home |
| MerchantCity | 1..13 | AN | Conditional | City of merchant or contact information (f.ex. The Shop, +123456789) |
| MerchantZipCode | 1..10 | AN | Conditional | ZipCode of merchant shop |
| MerchantCountry | 2 | A | Conditional | Two letter country code in uppercase (f.ex. GB, US) |
Refund and Partial Refunds must refer to the original transaction by having exactly the same DateAndTime and RRN as the original authorization.
Table GA.2 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantID | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalID | Optional | A terminal id in B-Gateway for the merchant requesting services. |
| TransType | Echo | 1 = Normal purchase transaction 3 = Refund 5 = Pre-Authorize |
| TrAmount | Echo | Amount, note for example 100 USD is 10000 because the amount is represented in cents |
| TrCurrency | Echo | Transaction currency ISO 4217 352 => ISK 978 => EUR |
| DateAndTime | Echo | YYMMDDhhmmss. When repeated use original date and time |
| PAN | Conditional | Card number – Used if a card number is entered manually. See also Track1/Track2 |
| RRN | Mandatory | Retrieval Reference Number – Reference number for transaction. |
| Transaction | Conditional | Unique number of the transaction within batch. |
| Batch | Conditional | Unique number of the batch in use for this terminal. |
| CVCResult | Conditional | If available indicates how the issuer processed theCVC. Values: M = Valid CVC N = Invalid CVC P = CVC not processed (issuer unavailable) |
| CardAccId | Mandatory | Card Acceptor Identification Code Code Identifying the card acceptor. This Id is issued by the acquirer |
| CardAccTerminal | Optional | Card Acceptor Terminal Identification Code Code Identifying the terminal the card acceptor is using |
| CardAccName | Mandatory | Card Acceptor Name and Location Name\Street\City\Postal Code\Region (two digit US state code or three digit ISO alpha country code if outside US)\Country Code as in ISO3166 |
| AuthCode | Mandatory | Authorization code if the transaction was accepted |
| ActionCode | Mandatory | Reason code for response |
| StoreTerminal | Mandatory | A numeric code that identifies the store and terminal within each merchant chain. |
| CardType | Mandatory | If available this will indicate the name of the card type |
| Message | Optional | Contains a text message if form error occurs |
Getting authorizations - XML examples
GAXML.1 – An example of authorization request
<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>2</MerchantID>
<TerminalID>1</TerminalID>
<TransType>5</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>0705</ExpDate>
<RRN>TESTING00001</RRN>
<CVC2>123</CVC2>
</getAuthorization>
GAXML.2 – An example of an authorization capture
<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>2</MerchantID>
<TerminalID>1</TerminalID>
<TransType>1</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<RRN>TESTING00001</RRN>
<AuthCode>060215012345</ AuthCode >
</getAuthorization>
GAXML.3 – An example of refund of sale
<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>1</MerchantID>
<TerminalID>1</TerminalID>
<TransType>3</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<RRN>TESTING00001</RRN>
</getAuthorization>
GAXML.4 – An example of partial reversal of sale
<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>1</MerchantID>
<TerminalID>1</TerminalID>
<TransType>4</TransType>
<TrAmount>100000</TrAmount>
<NewAmount>30000</NewAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<RRN>TESTING00001</RRN>
</getAuthorization>
GAXML.1 – An example of authorization request with Dynamic Descriptor
<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>2</Processor>
<MerchantID>2</MerchantID>
<TerminalID>1</TerminalID>
<TransType>1</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>0705</ExpDate>
<RRN>TESTING00001</RRN>
<CVC2>123</CVC2>
<MerchantName>The Shop</MerchantName>
<MerchantHome>The Road 123</MerchantHome>
<MerchantCity>+123456789</MerchantCity>
<MerchantZipCode>AL123</MerchantZipCode>
<MerchantCountry>UK</MerchantCountry>
</getAuthorization>
Cancelling authorizations
This operation cancels a previously authorized transaction. The previously authorized transaction is found by searching for the AuthCode of the transaction. If no AuthCode is present in a request, the most recent transaction that matches the criteria (i.e. the rest of the input request) is cancelled. Transactions authorized with TransType=1 can only be cancelled while the batch they belong to is still open. Transactions authorized with TransType=5 can always be cancelled as they don’t belong to any batches.
The card number and amount must be the same as in the original transaction. In the event of an error, such as timeout in communications, the RRN number of the transaction in the error must be included in the cancelling process.
Authorizations can be cancelled if the batch they belong to is still open. If it is closed then a refund transaction must be used. Pre-Authorize transaction can be cancelled after the batches are closed since pre-authorized transactions do not belong to batches.
Cancelling authorizations - XML explanations
Table CA.1 – Field explanations for a sent XML
| Field | Length | Form | Type | Explanation |
|---|---|---|---|---|
| Version | 4 | AN | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | 7 | N | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantID | ..8 | AN | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalID | ..8 | AN | Optional | A terminal id in B-Gateway for the merchant requesting sevices. Must be set if default terminal is not defined for merchant. |
| TransType | 1 | N | Mandatory | Same as the original transaction |
| TrAmount | ..12 | N | Mandatory | Same as the original transaction |
| TrCurrency | 3 | N | Mandatory | Same as the original transaction |
| DateAndTime | 12 | N | Mandatory | YYMMDDhhmmss. Same as the original transaction |
| PAN | LL..19 | N | Conditional | Card number – Same as the original transaction. If PAN is empty then DateAndTime + RRN will be used to find PAN in original transaction. |
| Track1 | LL..76 | AN | Conditional | Same as the original transaction |
| Track2 | LL..37 | Z | Conditional | Same as the original transaction |
| RRN | 12 | AN | Mandatory | Retrieval Reference Number – Reference number for transaction. Same as the original transaction |
| AuthCode | ..6 | AN | Conditional | Same as the original transaction |
Table CA.2 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantID | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalID | Optional | A terminal id in B-Gateway for the merchant requesting sevices. Must be set if default terminal is not defined for merchant. |
| TransType | Echo | Same as the original transaction |
| TrAmount | Echo | Same as the original transaction |
| TrCurrency | Echo | Same as the original transaction |
| DateAndTime | Echo | YYMMDDhhmmss. Same as the original transaction |
| PAN | Conditional | Card number – Same as the original transaction |
| RRN | Mandatory | Retrieval Reference Number – Reference number for transaction. Same as the original transaction |
| Transaction | Conditional | Number of the transaction. Same as the original transaction |
| Batch | Conditional | Number of the batch in use. Same as the original transaction |
| CardAccId | Mandatory | Code Identifying the card acceptor. Same as the original transaction |
| CardAccTerminal | Mandatory | Same as the original transaction |
| CardAccName | Mandatory | Card Acceptor Name and Location Name\Street\City\Postal Code\Region (two digit US state code or three digit ISO alpha country code if outside US)\Country Code as in ISO3166 |
| AuthCode | Mandatory | Authorization code if the transaction was accepted |
| ActionCode | Mandatory | Reason code for response |
| StoreTerminal | Mandatory | A numeric code that identifies the store and terminal within each merchant chain. |
| CardType | Mandatory | If available this will indicate the name of the card type |
| Message | Optional | A message in comprehension with the Action Code |
Cancelling authorizations – XML examples
CAXML.1 – An example of sent XML
<?xml version='1.0' encoding="utf-8"?>
<cancelAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>2</MerchantID>
<TerminalId>1</TerminalId>
<TransType>1</TransType>
<TrAmount>000000100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>1405</ExpDate>
<RRN>060215012345</RRN>
<AuthCode>809285</AuthCode>
</cancelAuthorization>
Virtual card numbers
Credit card numbers need not be sent into getAuthorization, instead virtual card numbers can be used. This enhances security as it eliminates the need to store sensetive credit card information in local data sources.
Virtual card numbers - XML explanations
Table VA.1 – Field explanations for a sent XML
| Field | Length | Form | Type | Explanation |
|---|---|---|---|---|
| MerchantContractNumber | 7 | AN | Mandatory | Contract number issued by SaltPay. |
| PAN | 16 | N | Mandatory | Card number |
Table VA.2 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| VirtualCard | Mandatory | Card number that can be used as reference to the real card number in authorization. |
Cancelling authorizations – XML examples
VCXML.1 – An example of sent XML
<?xml version='1.0' encoding="utf-8"?>
<getVirtualCard>
<MerchantContractNumber>7891234</MerchantContractNumber>
<PAN>5555544433331111</PAN>
</ getVirtualCard >
Creating new batches
New batch closes the currently open batch and opensa new one.
If the currently open batch has no transactions associated with it, the batch will be considered as being the new batch, thus it will not be closed nor will a new batch be opened.
Batch numbers controlled by the Authorization Services
This is the preferred way of handling batches. The merchant sends in authorization requests to the Authorization Services. The Authorization Services will add the batch and transaction numbers to the transaction as needed. When the merchant wants to close the batch the merchant can use the NewBatch function orthe Authorization Services can take care of this daily at predefined time.
Batch numbers controlled by the merchant
The merchant adds the batch and transaction numbers to the authorization request. In order to start a new batch the merchant simply increments the batch number and starts the transaction number back at number 1. The batch number must be unique for particular terminal within the year and in ascending sequence.Transaction numbers must be unique within a batch number.
Creating new batches – XML explanations
Table CNB.1 – Field explanations for a sent XML
| Field | Length | Form | Type | Explanation |
|---|---|---|---|---|
| Version | 4 | AN | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | 7 | N | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantId | ..8 | AN | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalId | ..8 | AN | Optional | If not set then the batch for the default terminal will be closed. If set then the insent terminal will be close. |
| DateAndTime | 12 | AN | Optional | YYMMDDhhmmss. Only used for documentation purposes |
Table CNB.2 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantId | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalId | Optional | A terminal id in B-Gateway for the merchant requesting sevices |
| DateAndTime | Echo | YYMMDDhhmmss. Same as the request |
| NewBatch | Conditional | Number of the new batch in use |
| OldBatch | Conditional | Number of the batch just closed |
| CardAccTerminal | Optional | Terminal id |
| ActionCode | Mandatory | Reason code for response |
| StoreTerminal | Mandatory | If available this will indicate the name of the card type |
Creating new batches – XML examples
CNBXML.1 – An example of a sent XML
<?xml version='1.0' encoding="utf-8"?>
<newBatch>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantId>2</MerchantId>
<TerminalId>1</TerminalId>
<DateAndTime>060216103700</DateAndTime>
</newBatch>
Getting transaction lists
Client applications can request a transaction list from the authorization service listing on either batch or transaction level details about transactions processed through the service.
It is possible to specify a batch number in the request to get all transactions that belong to that given batch. It is also possible to get a listof transactions for a given time period.
Getting transaction lists – XML explanations
Table TL.1 – Field explanations for a sent XML
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantId | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalId | Optional | A terminal id in B-Gateway for the merchant requesting services. Must be set if default terminal is not defined for merchant. |
| BatchNumber | Conditional | Batch number. If the BatchNumber is omitted, the response will only include batchnumbers processed during the given time period. Otherwise a list of transactions for the given batchnumber is returned. |
| FromDate | Conditional | Format:YYYYMMDD. Mandatory field if BatchNumber is empty. |
| ToDate | Conditional | Format:YYYYMMDD. Only used if BatchNumber is empty. If this parameter is not set, current date will be used as ToDate. |
| RRN | Conditional | Searches all batches for transactions with the given RRN |
Tables TL.2 and TL.3 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantID | Mandatory | An Id in B-Gateway of the merchant requesting services |
| ActionCode | Mandatory | Reason code for response |
Explanations for each transaction within the batch
| Field | Type | Explanation |
|---|---|---|
| TransType | Mandatory | 1 = Normal purchase transaction 3 = Refund 5 = Pre-Authorize |
| TransactionNumber | Mandatory | Number of the transaction |
| BatchNumber | Mandatory | Number of the requested batch |
| TransactionDate | Mandatory | YYMMDDhhmmss. Date and time of the transaction |
| PAN | Mandatory | Card number – Used if a card number is entered manually |
| RRN | Mandatory | Retrieval Reference Number –Reference number for transaction |
| ActionCode | Conditional | Reason code for response |
| AuthorizationCode | Mandatory | Authorization code of a previous pre-authorized transaction. Include this code to use the previously gotten authorization code |
| TrAmount | Mandatory | Amount, note for example 100 USD is 10000 because the amount is represented in cents |
| TrCurrency | Mandatory | Transaction currency ISO 4217 352 => ISK 978 => EUR |
| CardType | Conditional | If available this will indicate the name of the card type |
| Voided | Mandatory | Voided can have values T (True) and V (Void transactions). A transaction that is voided will get Voided as T, the voiding transaction (cancelAuthorization) will get voided as V. The void status can only be created by cancelAuthorization(). |
| Status | Mandatory | Status on transaction can have the following values 1: Sale initial status 2: Sale successful 3: Sale failed 4: Refund initial status 5: Refund successful 6: Refund failed 7: Pre-authorization initial status 8: Pre-authorization successful 9: Pre-authorization failed 10: Reversal initial status 11: Reversal successful 12: Reversal failed 14: Financial record sent A successful transaction will be in state 2 (or 6 for refund) and end up in state 14 when the financial record has been sent to the card schema. Other statuses are more for information purposes, i.e. |
| have no financial impact. | ||
| TerminalNr | Id of terminal being used during authorization | |
| Credit | Conditional | Contains 1 if OCT/CFT transaction |
Getting transaction lists – XML examples
TLXML.1 – An example of a sent XML
<?xml version="1.0" encoding="utf-8"?>
<TransactionListRequest>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantId>2</MerchantId>
<BatchNumber>3</BatchNumber>
</TransactionListRequest>
Getting Disputed Transactions
Client applications can request a list of disputed transactions. All authorization transactions have a unique numbernamed Acquiring Reference, for each transaction that has a chargeback there will be a list (1 or more) of chargeback records detailing the history of the chargeback. They can be fetched by using the Acquiring Reference.
Dispute types returned are as follows
- Chargeback
- Issuer to acquirer. Chargeback of the original transaction, short code is ‘C’. If the chargeback is partial, that is only partial amount of the original transaction is used, then the short code is ‘PC’
- Retrieval Request / Information Retrieval
- Issuer to acquirer. Request for information regarding the original transaction, non financial impact, short code is ‘RR’.
- Chargeback Reversal
- Issuer to acquirer. Reverses the chargeback, short code is ‘CR’.
- Second Presentment / Re-Presentment
- Acquirer to Issuer. Negates the chargeback by sending the financial transaction again, initiated by merchant, short code is ‘SP’.
- If the re-presentment is partial, that is only partial amount of the original transaction is used, then the short code is ‘PSP’
- Second Chargeback / Arbitration Chargeback
- Issuer to acquirer. Chargeback in response to the re-presentment, short code is ‘AC’. If the arbitration chargeback is partial, that is only partial amount of the original transaction is used, then the short code is ‘PAC’
- Second Presentment Reversal
- Acquirer to Issuer. Negates a Second Presentment /Re-Presentment, can be caused by second presentment being denied by schemaor manual mistakes. Rarely used. short code is ‘SPR’.
The chargeback list describes the communication between acquirer and issuer during dispute, a path for a long running dispute might becreating the following four records
- Retrieval Request / Information Retrieval: Issuer needs more information to determine if the original transaction should be accepted or a chargeback sent.
- Chargeback: Issuer requests a chargeback from acquirer. Issuer can always back out of the chargeback by doing a chargeback reversal.
- Second Presentment / Re-Presentment: Acquirer does not accept the chargeback and resends the transaction.
- Second Presentment Reversal: Acquirer negates a second presentment.
- Issuer might then end with Second Chargeback(Issuerre-request for chargeback)
A rare occurrence that still happens once in a while is double registration of chargeback.
- Chargeback: Issuer requests a chargeback from acquirer
- Chargeback: A second chargeback from issuer to acquirer
- Chargeback Reversal: Issuer reverses one chargeback for acquirer does a representment.
Getting disputed transactions
Table DT.1 – Parameters for getDisputedTransactions ()
| Field | Type | Explanation |
|---|---|---|
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantContractNumber | Mandatory | Contract number issued by SaltPay. |
| DateFrom | Mandatory | Returns all disputed transactions from date DateFrom. Date format YYYYMMDD. |
| DateTo | Mandatory | Returns all disputed transactions up to and including date DateFrom. Date format YYYYMMDD. |
Table DT.2 – Field explanations for the status record contained in received XML
| Field | Type | Explanation |
|---|---|---|
| ResultCode | Mandatory | Can have values 0 = “Success”, 10 = “Information” (f.ex. No Data Found), 30 = “Error” |
| ResultText | Mandatory | Text description for ResultCode, f.ex. “Success”, “Error”, “No Data Found” |
| ErrorMessage | Mandatory | Detailed error description |
| MessageId | Mandatory | Error description code of ErrorMessage if applicable |
| ReferenceValue | Mandatory | Id of record within list where error occurred. Onlyreturned if applicable |
| StackTrace | Mandatory | Stacktrace of error if applicable |
Table DT.3 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| MerchantNumber | Mandatory | Merchant contract number |
| ProcessingTime | Mandatory | Date and time of record processing at SaltPay, yyyy-mmddThh:mm:ss |
| Date | Mandatory | Date of record creation, yyyy-mm-dd |
| Brand | Mandatory | Card brand type |
| Type | Mandatory | See table above |
| Amount | Mandatory | Current amount |
| Currency | Mandatory | Current currency |
| ReasonCode | Mandatory | Code describing reason for dispute |
| ReasonText | Mandatory | Text describing reason for dispute |
| AcquiringReferenceData | Mandatory | Acquirer reference |
| BatchDate | Mandatory | Batch date of transaction, yyyy-mm-dd |
| TerminalId | Mandatory | Transaction terminal id |
| RRN | Mandatory | Retrieval Reference Number – Reference number for transaction |
| CardNumber | Mandatory | Masked cardnumber in transaction |
| OriginalAmount | Mandatory | Amount in transaction |
| OriginalCurrency | Mandatory | Currency of transaction |
| OriginalDate | Mandatory | Date of transaction, yyyy-mm-dd |
| AuthorizationCode | Mandatory | Tranasction authorization number |
Getting disputed transaction list – XML examples
DTXML.1 – An example of a sent and received received XML
<?xml version="1.0" encoding="utf-8"?>
<getDisputedTransactions>
<Processor>21</Processor>
<MerchantContractNumber>9275444</MerchantContractNumber>
<DateFrom>20101021</DateFrom>
<DateTo>20111025</DateTo>
</getDisputedTransactions>
<?xml version="1.0"?>
<DisputedTransactionResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<DisputedTransactionList>
<DisputedTransaction>
<MerchantNumber>9275444</MerchantNumber>
<ProcessingTime>2008-09-18T00:00:00</ProcessingTime>
<Date>2008-09-18</Date>
<Brand>MC</Brand>
<Type>C</Type>
<Amount>2000000</Amount>
<Currency>352</Currency>
<ReasonCode>4809</ReasonCode>
<ReasonText>TRANSACTION NOT RECONCILED</ReasonText>
<AcquiringReferenceData>5414838259002000123123</AcquiringReferenceData>
<BatchDate>2008-06-23</BatchDate>
<TerminalId>00010002</TerminalId>
<RRN>111222</RRN>
<CardNumber>002359*********3123</CardNumber>
<OriginalAmount>20000</OriginalAmount>
<OriginalCurrency>352</OriginalCurrency>
<OriginalDate>2008-06-21</OriginalDate>
<AuthorizationCode>0</AuthorizationCode>
</DisputedTransaction>
</DisputedTransactionList>
</DisputedTransactionResponse>
Getting Fraud Transactions
Client applications can request a list of fraud transactions.
Getting fraud transactions
Table FT.1 – Parameters for getFraudTransactions ()
| Field | Type | Explanation |
|---|---|---|
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantContractNumber | Mandatory | Contract number issued by SaltPay. |
| DateFrom | Mandatory | Returns all fraud transactions from date DateFrom. Date format YYYYMMDD. |
| DateTo | Mandatory | Returns all disputed transactions up to and including date DateFrom. Date format YYYYMMDD. |
Table FT.2 – Field explanations for the status record contained in received XML
| Field | Type | Explanation |
|---|---|---|
| ResultCode | Mandatory | Can have values 0 = “Success”, 10 = “Information” (f.ex. No Data Found), 30 = “Error” |
| ResultText | Mandatory | Text description for ResultCode, f.ex. “Success”, “Error”, “No Data Found” |
| ErrorMessage | Mandatory | Detailed error description |
| MessageId | Mandatory | Error description code of ErrorMessage if applicable |
| ReferenceValue | Mandatory | Id of record within list where error occurred. Only returned if applicable |
| StackTrace | Mandatory | Stacktrace of error if applicable |
Table DT.3 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| MerchantNumber | Mandatory | Merchant contract number |
| ProcessingTime | Mandatory | Date and time of record processing at SaltPay, yyyymm-ddThh:mm:ss |
| Date | Mandatory | Date of record creation, yyyy-mm-dd |
| Brand | Mandatory | Card brand type |
| Type | Mandatory | Currently can only have the value ‘F’ (Fraud) |
| ReasonCode | Mandatory | Code describing reason for dispute |
| ReasonText | Mandatory | Text describing reason for dispute |
| AcquiringReferenceData | Mandatory | Acquirer reference to the original authorization transaction that this dispute record relates to. For each disputed transaction there exists 1 or more dispute record that all will have the same acquirer reference. |
| NotificationCode | Mandatory | Notification code 1 = Addition2 = Addition of subsequent duplicate transaction 3 = Change 4 = Delete 5 = Reactivate |
| IssuerGeneratedAuthorization | Mandatory | VISA specific, Y = Issuer authorized transaction X = Transaction authorized but not by issuer N = Transaction not authorized |
| AccountSequenceNumber | Mandatory | VISA specific, identifies a transaction within the account number. A maximum of 1000 transactions on a specific account may be added to the Visa fraud master file. The member may also pre-assign a sequence number within the 4000–4999 range. account |
| FraudInvestigationStatus | Mandatory | VISA specific, member-assigned, may be 00 through 99 or AA through ZZ |
| CustomerReference | Mandatory | VISA specific |
| BatchDate | Mandatory | Batch date, yyyy-mm-dd |
| TerminalId | Mandatory | Transaction terminal id |
| RRN | Mandatory | Retrieval Reference Number – Reference number for transaction |
| CardNumber | Mandatory | Masked cardnumber in transaction |
| OriginalBatchId | Mandatory | VISA specific, original batch id |
| OriginalAmount | Mandatory | Amount in transaction |
| OriginalCurrency | Mandatory | Currency of transaction |
| OriginalDate | Mandatory | Date of transaction, yyyy-mm-dd |
| AuthorizationCode | Mandatory | Tranasction authorization number |
Getting fraud transaction list – XML examples
DTXML.1 – An example of a received XML
<?xml version="1.0"?>
<FraudTransactionResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<FraudTransactionList>
<FraudTransaction>
<MerchantNumber>9577851</MerchantNumber>
<ProcessingTime>2009-10-14T10:25:00.60831</ProcessingTime>
<Date>2009-03-12</Date>
<Brand>MC</Brand>
<Type>F</Type>
<ReasonCode>4</ReasonCode>
<ReasonText>COUNTERFEIT</ReasonText>
<AcquiringReferenceData>5414838196002000012345</AcquiringReferenceData>
<NotificationCode>1</NotificationCode>
<IssuerGeneratedAuthorization></IssuerGeneratedAuthorization>
<AccountSequenceNumber></AccountSequenceNumber>
<FraudInvestigationStatus></FraudInvestigationStatus>
<CustomerReference></CustomerReference>
<BatchDate>2008-06-23</BatchDate>
<TerminalId>00010002</TerminalId>
<RRN></RRN>
<CardNumber>398320******2345</CardNumber>
<OriginalBatchId>1</OriginalBatchId>
<OriginalAmount>10000</OriginalAmount>
<OriginalCurrency>352</OriginalCurrency>
<OriginalDate>2008-06-21</OriginalDate>
<AuthorizationCode>0</AuthorizationCode>
</FraudTransaction>
</FraudTransactionList>
</FraudTransactionResponse>
Getting Settlement Data
Client applications can fetch settlement data.
Settlement can contain one or more batches, and each batch contains one or more transaction.
Settlement data can be fetched with the following calls
Getting settlement list
Table SD.1 – Parameters for getSettlement ()
| Field | Type | Explanation |
|---|---|---|
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantContractNumber | Mandatory | Contract number issued by SaltPay. |
| DateFrom | Mandatory | Returns all settlements from date DateFrom. Date format YYYYMMDD. |
| DateTo | Mandatory | Returns all settlement up to and including DateTo. Date format YYYYMMDD. |
Getting a list of batches in settlement
Table SD.2 – Parameters for getSettlementBatch()
| Field | Type | Explanation |
|---|---|---|
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantContractNumber | Mandatory | Contract number issued by SaltPay. |
| SettlementNumber | Mandatory | Unique number of settlement |
Getting a list of transactions in batches. BatchDate and BatchNumber are unique for each batch.
Table SD.3 – Parameters for getSettlementTransactions()
| Field | Type | Explanation |
|---|---|---|
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantContractNumber | Mandatory | Contract number issued by SaltPay. |
| BatchNumber | Mandatory | Batch number |
| BatchDate | Mandatory | Batch date, format YYYYMMDD |
Getting a list of chargebacks in settlement
Table SD.4 – Parameters for getSettlementChargeback()
| Field | Type | Explanation |
|---|---|---|
| Processor | Mandatory | An ID issued by SaltPay to the processor using this interface on behalf of the merchant |
| MerchantContractNumber | Mandatory | Contract number issued by SaltPay. |
| SettlementNumber | Mandatory | Unique number of settlement |
Table SD.4 – Field explanations for the status record contained in received XML
| Field | Type | Explanation |
|---|---|---|
| ResultCode | Mandatory | Can have values 0 = “Success”, 10 = “Information” (f.ex. No Data Found), 30 = “Error” |
| ResultText | Mandatory | Text description for ResultCode, f.ex. “Success”, “Error”, “No Data Found” |
| ErrorMessage | Mandatory | Detailed error description |
| MessageId | Mandatory | Error description code of ErrorMessage if applicable |
| ReferenceValue | Mandatory | Id of record within list where error occurred. Only returned if applicable |
| StackTrace | Mandatory | Stacktrace of error if applicable |
Tables SD.5 – Settlement
| Field | Type | Explanation |
|---|---|---|
| SettlementNumber | Mandatory | Settlement number |
| SettlementDate | Mandatory | Date of settlement |
| MastercardDomesticAmount | Conditional | Not in use |
| MastercardInternationalAmount | Conditional | Not in use |
| MastercardOtherAmount | Conditional | Not in use |
| JcbAmount | Conditional | Not in use |
| VisaAmount | Conditional | Not in use |
| AmexAmount | Conditional | Not in use |
| TotalAmount | Mandatory | Total amount in settlement |
| TransactionCountInSettlement | Mandatory | Number of transactions in settlement |
| SettlementCurrencyCode | Mandatory | Currency code of settlement |
| DeductionAmount | Mandatory | Deduction amount of settlement amount |
| RefundAmount | Mandatory | Refund amount in settlement |
Tables SD.6 – Settlement deductions
| Field | Type | Explanation |
|---|---|---|
| SettlementNumber | Mandatory | Settlement number |
| Code | Mandatory | Code describing deduction type |
| CodeDescription | Mandatory | Text describing deduction type |
| Amount | Mandatory | Deduction amount |
| DeductionCurrencyCode | Mandatory | Currency code of deduction |
SDXML.5 and SDXML.6 – An example of a received XML with settlement and deduction
Request:
<?xml version="1.0" encoding="utf-8"?>
<getSettlements>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<DateFrom>20110129</DateFrom>
<DateTo>20110930</DateTo>
</getSettlements>
Response:
<?xml version="1.0"?>
<SettlementResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<Settlement>
<MerchantNumber>9999999</MerchantNumber>
<SettlementNumber>4290310</SettlementNumber>
<SettlementDate>2014-06-04T00:00:00</SettlementDate>
<MastercardDomesticAmount>0.0</MastercardDomesticAmount>
<MastercardInternationalAmount>0.0</MastercardInternationalAmount>
<MastercardOtherAmount>0</MastercardOtherAmount>
<JcbAmount>0</JcbAmount>
<VisaAmount>0</VisaAmount>
<AmexAmount>0</AmexAmount>
<TotalAmount>220</TotalAmount>
<TransactionCountInSettlement>0</TransactionCountInSettlement>
<SettlementCurrencyCode>USD</SettlementCurrencyCode>
<DeductionAmount>197.62</DeductionAmount>
<RefundAmount>0.0</RefundAmount>
<SettlementDeductions>
<SettlementNumber>4290310</SettlementNumber>
<Code>F_MSC_MC</Code>
<CodeDescription>Merchant Commission MC</CodeDescription>
<Amount>-21.04</Amount>
<DeductionCurrencyCode>USD</DeductionCurrencyCode>
<Id/>
</SettlementDeductions>
<SettlementDeductions>
<SettlementNumber>4290310</SettlementNumber>
<Code>F_CBK</Code>
<CodeDescription>Chargeback Fee</CodeDescription>
<Amount>-30</Amount>
<DeductionCurrencyCode>USD</DeductionCurrencyCode>
</SettlementDeductions>
</Settlement>
</SettlementResponse>
SD.7 –List of batches in settlement
| Field | Type | Explanation |
|---|---|---|
| BatchNumber | Mandatory | Batch number |
| BatchDate | Mandatory | Date of batch |
| SettlementDate | Mandatory | Settlement date |
| SettlementNumber | Mandatory | Settlement number |
| TransactionCountInBatch | Mandatory | Number of transactions in batch |
| TransactionSumInBatch | Mandatory | Amount in transactions in batch |
| BatchCurrencyCode | Mandatory | Currency code of amounts |
SDXML.7 – Example of received batchlist
Request:
<?xml version="1.0" encoding="utf-8"?>
<getSettlementBatch>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<SettlementNumber>4245</SettlementNumber>
</getSettlementBatch>
Response:
<?xml version="1.0"?>
<SettlementBatchResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Succcess</ResultText>
</Status>
<SettlementBatch>
<BatchNumber>116757</BatchNumber>
<BatchDate>2007-12-05T00:00:00</BatchDate>
<SettlementDate>2008-01-02T00:00:00</SettlementDate>
<SettlementNumber>4245</SettlementNumber>
<TransactionCountInBatch>9</TransactionCountInBatch>
<TransactionSumInBatch>18405.00</TransactionSumInBatch>
<BatchCurrencyCode>ISK</BatchCurrencyCode>
</SettlementBatch>
</SettlementBatchResponse>
SD.8 – Transactions in batches
| Field | Type | Explanation |
|---|---|---|
| TransactionDate | Mandatory | Date of transaction |
| Amount | Mandatory | Transaction amount |
| CurrencyCode | Mandatory | Currency code of amounts in transaction |
| SlipNumber | Mandatory | Slip number |
| RRN | Mandatory | Retrieval reference number |
| CardNumber | Mandatory | Card number |
| CardType | Mandatory | Card type |
| OriginalAmount | Mandatory | Original amount on slip |
| OriginialAmountCurrencyCode | Mandatory | Amount in currency code |
| BatchNumber | Mandatory | Number of batch containing transaction |
| SettlementDate | Mandatory | Date of settlement |
| SettlementNumber | Mandatory | Number of settlement containing transaction |
SDXML.8 – An XML example of a received transaction list
Request:
<?xml version="1.0" encoding="utf-8"?>
<getSettlementTransactions>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<BatchNumber>101166</BatchNumber>
<BatchDate>20110105</BatchDate>
</getSettlementTransactions>
Response:
<?xml version="1.0"?>
<SettlementTransactionResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<SettlementTransaction>
<TransactionDate>2011-01-05T00:00:00</TransactionDate>
<Amount>687.00</Amount>
<CurrencyCode>ISK</CurrencyCode>
<Slipnumber>9372</Slipnumber>
<RRN>rr1402530644</RRN>
<Cardnumber>544602******8005</Cardnumber>
<Cardtype>MD</Cardtype>
<OriginialAmount>687.00</OriginialAmount>
<OriginialAmountCurrencyCode>SEK</OriginialAmountCurrencyCode>
<BatchNumber>101166</BatchNumber>
<SettlementDate>2008-01-02T00:00:00</SettlementDate>
<SettlementNumber>2727</SettlementNumber>
</SettlementTransaction>
</SettlementTransactionResponse>
SD.9 – Chargeback transactions in settlements
| Field | Type | Explanation |
|---|---|---|
| TransactionDate | Mandatory | Date of transaction |
| Amount | Mandatory | Transaction amount |
| CurrencyCode | Mandatory | Currency code of amounts in transaction |
| SlipNumber | Mandatory | Slip number |
| RRN | Mandatory | Retrieval reference number |
| CardNumber | Mandatory | Card number |
| CardType | Mandatory | Card type |
| OriginalAmount | Mandatory | Original amount on slip |
| OriginialAmountCurrencyCode | Mandatory | Amount in currency code |
| BatchNumber | Mandatory | Number of batch containing transaction |
| SettlementDate | Mandatory | Date of settlement |
| SettlementNumber | Mandatory | Number of settlement containing transaction |
| AcquirerReference | Mandatory | Acquirer reference for chargeback. Unique number for the authorization transaction. Can be used to reference a list of dispute records related to the chargeback. |
| ChargebackDate | Mandatory | Date of chargeback registration |
| ChargebackAmount | Mandatory | Amount of chargeback |
SDXML.9 – An XML example of a received chargeback list
Request:
<?xml version="1.0" encoding="utf-8"?>
<getSettlementChargeback>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<SettlementNumber>7566</SettlementNumber>
</getSettlementChargeback>
Response:
<?xml version="1.0"?>
<SettlementChargebackResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>OK</ResultText>
</Status>
<SettlementChargeback>
<SettlementDate>2011-08-10T00:00:00</SettlementDate>
<SettlementNumber>7566</SettlementNumber>
<BatchNumber>162</BatchNumber>
<Amount>-34.9500000000000000</Amount>
<CurrencyCode>USD</CurrencyCode>
<Cardnumber>4060 42** **** 8831</Cardnumber>
<Cardtype>04</Cardtype>
<TransactionDate>2011-07-08T00:00:00</TransactionDate>
<OriginialAmountCurrencyCode>USD</OriginialAmountCurrencyCode>
<OriginialAmount>-34.95</OriginialAmount>
<Slipnumber>777003</Slipnumber>
<RRN>AA1234567890</RRN>
<AcquirerReference>5414811112222000025737</AcquirerReference>
<ChargebackDate>2011-08-03T00:00:00</ChargebackDate>
<ChargebackAmount>187</ChargebackAmount> </SettlementChargeback>
</SettlementChargebackResponse>
Sending detailed data
This addition to get Authorization is used to supply detailed invoice after the financial transaction has been processed. In order to match the detail transaction to the financial transaction some parameters must be supplied.
Sending detail data – XML explanations
Tables SDD.1, SDD.2 and SDD.3 – Field explanations for a sent XML
The input is split into a header and detail. Following the header is a detailed description of the invoice in XML format. The invoice itself is split into a header record (A4) and detail
records (A6) as follows:
Main header
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” |
| Processor | Mandatory | An Id issued by SaltPay to the processor using this interface on behalf of the merchant. |
| MerchantId | Mandatory | An Id in B-Gateway of the merchant requesting services |
| TerminalId | Optional | A terminal id in B-Gateway for the merchant requesting sevices. |
| TransType | Mandatory | Same as in the original transaction |
| TrAmount | Mandatory | Same as in the original transaction |
| TrCurrency | Mandatory | Same as in the original transaction |
| DateAndTime | Mandatory | Same as in the original transaction |
| PAN | Mandatory | Same as in the original reply |
| ExpDate | Mandatory | Expiration date – YYMM |
| RRN | Mandatory | Same as in the original reply |
| Transaction | Optional | Same as in the original reply |
| Batch | Optional | Same as in the original reply |
| AuthCode | Conditional | Same as in the original reply |
Invoice header (A4):
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000”. |
| MessageNumber | Mandatory | Message number (sequence number of line within file) |
| InvoiceNumber | Mandatory | Invoice number |
| InvoiceDate | Mandatory | Invoice date (yyyymmdd) |
| Reference | Optional | Reference number |
| MerchantSSN | Mandatory | Merchant social security number |
| MerchantVATNumber | Mandatory | Merchant VAT number |
| Amount1 | Mandatory | Total (A6 Amount) |
| Discount | Optional | Total (A6*DiscountAmount) Discount |
| AmountWithDiscount | Optional | Total (A6*AmountWithDiscount) Amount with discount |
| Vgju | Optional | Total (A6*Vgju) (zero filled) |
| Amount3 | Optional | Total (A6*Amount3) (same as AmountWithDiscount) |
| TotalVAT | Mandatory | Total (A6*VATAmount) VAT |
| AmountWithVAT | Mandatory | Total (A6*AmountWithVAT) amount with VAT |
| InvoiceAmount | Mandatory | Total invoice |
| Rounding | Optional | Round off amount in “aurar” |
| RikiskaupFee | Optional | Total Rikiskaup fee |
| GLAccount | Optional | General ledger account number |
| RecordNumber | Mandatory | Record number within invoice (0001 for header) |
| NumberOfRecords | Mandatory | Number of records in invoice (A4+number of A6) |
| SlipNumber | Optional | Slip number |
| Comments | Optional | Comments |
| OrderNumber | Optional | Order number |
| OrderDate | Optional | Order date |
| DeliveryDate | Optional | Delivery date |
| DeliveryAddress | Optional | Delivery address |
Invoice detail (A6):
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000”. |
| MessageNumber | Mandatory | Message number (sequence number of line within file) |
| ProductCode | Mandatory | Product code |
| ItemDescription | Mandatory | Item description |
| UNSPSCcode | Optional | UNSPSC code |
| UNSPSCdescription | Optional | UNSPSC description |
| CommodityCode | Optional | Commodity code |
| ItemQuantity | Mandatory | Item quantity |
| UnitOfMeasurement | Optional | Item unit of measure (ltr, km, kg....) |
| GrossValue | Mandatory | Unit price without VAT |
| Amount | Mandatory | Amount (ItemQuantity * GrossValue) |
| DiscountPercent | Optional | Discount percent (%) |
| DiscountAmount | Optional | Discount amount |
| AmountWithDiscount | Optional | Amount with discount (Amount – DiscountAmount) |
| Vgjp | Optional | “00000” |
| Vgju | Optional | “00000000000” |
| Amount3 | Optional | AmountWithDiscount |
| VATPercent | Mandatory | VAT % |
| VATAmount | Mandatory | VAT amount |
| AmountWithVAT | Mandatory | Amount with VAT (Amount3 + VATAmount) |
| RikiskaupFeePercent | Optional | Rikiskaup fee (%) |
| RikiskaupFee | Optional | Rikiskaup fee amount |
| GLAccount | Optional | General ledger account number |
| RecordNumber | Mandatory | Record number within invoice (0002-xxxx) |
| NumberOfRecords | Mandatory | Number of records in invoice (A4+number of A6) |
| SlipNumber | Optional | Slip number |
| Ref1 | Optional | Reference 1 |
| Ref2 | Optional | Reference 2 |
| Ref3 | Optional | Reference 3 |
| Ref4 | Optional | Reference 4 |
Table SDD.4 – Field explanations for a received XML
| Field | Type | Explanation |
|---|---|---|
| Version | Mandatory | Same value as in the request message |
| Processor | Mandatory | Same value as in the request message |
| MerchantId | Mandatory | Same value as in the request message |
| TerminalId | Mandatory | Same value as in the request message |
| TransType | Mandatory | Same value as in the request message |
| TrAmount | Mandatory | Same value as in the request message |
| TrCurrency | Mandatory | Same value as in the request message |
| DateAndTime | Mandatory | Same value as in the request message |
| PAN | Mandatory | Same value as in the request message |
| ExpDate | Mandatory | Same value as in the request message |
| RRN | Mandatory | Same value as in the request message |
| Transaction | Mandatory | Same value as in the request message |
| Batch | Mandatory | Same value as in the request message |
| CardAccID | Mandatory | Code Identifying the card acceptor. This Id is issued by the acquirer |
| CardAccTerminal | Mandatory | Code Identifying the terminal the card acceptor is using |
| AuthCode | Mandatory | Same value as in the request message |
| ActionCode | Mandatory | Reason code for response |
Sending detail data – XML examples
SDDXML.1 – An example of a sent XML
<?xml version="1.0" encoding="utf-8"?>
<DetailData>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantId>2</MerchantId>
<TransType>1</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>0506</ExpDate>
<RRN>404</RRN>
<Batch>3</Batch>
<A4>
<Version>1000</Version>
<MessageNumber>2</MessageNumber>
<InvoiceNumber>071897</InvoiceNumber>
<InvoiceDate>20060118</InvoiceDate>
<MerchantSSN>5415986459</MerchantSSN>
<MerchantVATNumber>079318</MerchantVATNumber>
<Amount1>100000</Amount1>
<TotalVAT>24500</TotalVAT>
<AmountWithVAT>124500</AmountWithVAT>
<InvoiceAmount>125000</InvoiceAmount>
<RecordNumber>1</RecordNumber>
<NumberOfRecords>1</NumberOfRecords>
<A6>
<Version>1000</Version>
<MessageNumber>2</MessageNumber>
<ProductCode>054</ProductCode>
<ItemDescription>Chocolate</ItemDescription>
<ItemQuantity>5</ItemQuantity>
<GrossValue>20000</GrossValue>
<Amount>1000</Amount>
<VATPercent>0,245</VATPercent>
<VATAmount>24500</VATAmount>
<AmountWithVAT>124500</AmountWithVAT>
<RecordNumber>1</RecordNumber>
<NumberOfRecords>1</NumberOfRecords>
</A6>
</A4>
</DetailData>
Sending passenger itinerary
This addition to getAuthorization is used to supply passenger itinerary data after the financial transaction has been processed. It currently only supports itineraries with four legs or less.
Sending passenger itinerary – XML explanations
Tables SPI.1, SPI.2 – Field explanations for a sent/received XML
The input is split into a header and detail. Following the header is a detailed description of the invoice in XML format. The invoice itself is split into a header record (A4) and detail records (A6) as follows:
Table SPI.1 – Passenger Itinerary information field explanations for a sent XML
| Field | Type | Length | Explanation |
|---|---|---|---|
| Version | Mandatory | Indicates the version of these specifications the client is using. Current version is “1000” | |
| TrDate | Mandatory | Same as in the original transaction | |
| TrTime | Mandatory | Same as in the original transaction | |
| PassengerName | Mandatory | 1..29 AN | Name of passenger to whom the ticket was issued |
| FlightNumber_1 | Mandatory | 3 AN | Flight number in leg 1 |
| TravelDate_1 | Mandatory | 6 | Traveldate of leg 1, format is YYMMDD. |
| DepartureAirport_1 | Mandatory | 3 AN | Departure airport, airport code can be obtained from OAG or equivalent. |
| CarrierCode_1 | Mandatory | 2 AN | Carrier code is a standard abbreviation for the airline carrier. Can be obtained from IATA, or an equivalent. Length |
| ServiceClassCode_1 | Optional | 3 N | Service type, such as first class, etc. Can be obtained from OAG or equivalent. |
| DestinationAirport_1 | Optional | 3 AV | Destination airport, airport code can be obtained from OAG or equivalent. |
| FareBaseCode_1 | Optional | 1..15 AN | Fare basis code contains a code that carriers assign to particular ticket type such as business class or discounted/refundable. |
| FlightNumber_2 | Optional | Same as in leg 1 | |
| TravelDate_2 | Optional | Same as in leg 1 | |
| DepartureAirport_2 | Optional | Same as in leg 1 | |
| CarrierCode_2 | Optional | Same as in leg 1 | |
| ServiceClassCode_2 | Optional | Same as in leg 1 | |
| DestinationAirport_2 | Optional | Same as in leg 1 | |
| FareBaseCode_2 | Optional | Same as in leg 1 | |
| FlightNumber_3 | Optional | Same as in leg 1 | |
| TravelDate_3 | Optional | Same as in leg 1 | |
| DepartureAirport_3 | Optional | Same as in leg 1 | |
| CarrierCode_3 | Optional | Same as in leg 1 | |
| ServiceClassCode_3 | Optional | Same as in leg 1 | |
| DestinationAirport_3 | Optional | Same as in leg 1 | |
| FareBaseCode_3 | Optional | Same as in leg 1 | |
| FlightNumber_4 | Optional | Same as in leg 1 | |
| TravelDate_4 | Optional | Same as in leg 1 | |
| DepartureAirport_4 | Optional | Same as in leg 1 | |
| CarrierCode_4 | Optional | Same as in leg 1 | |
| ServiceClassCode_4 | Optional | Same as in leg 1 | |
| DestinationAirport_4 | Optional | Same as in leg 1 | |
| FareBaseCode_4 | Optional | Same as in leg 1 | |
| TravelAgencyCode | Mandatory | 8 | Code of the travel agency issuing the ticket |
| TravelAgencyName | Mandatory | 25 | Name of travel agency issuing the ticket |
| TicketNumber | Mandatory | 15 | Number of the ticket |
Sending detail data – XML examples
SDDXML.1 – An example of a sent XML
<?xml version="1.0" encoding="utf-8"?>
<getAuthorization xmlns="http://tempuri.org/getAuthorization.xsd">
<Version>1000</Version>
<Processor>3</Processor>
<MerchantID>3</MerchantID>
<TerminalID>1</TerminalID>
<TransType>1</TransType>
<TrAmount>10000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>120325120000</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>1412</ExpDate>
<CVC2>111</CVC2>
<RRN>TESTAIR00111</RRN>
<PassengerItineraryData>
<A1>
<Version>10</Version>
<MessageNumber>1111111</MessageNumber>
<TrDate>20120222</TrDate>
<TrTime>151515</TrTime>
<PassengerName>Jane Doe</PassengerName>
<FlightNumber_1>111111</FlightNumber_1>
<TravelDate_1>20120111</TravelDate_1>
<DepartureAirport_1>KEF</DepartureAirport_1>
<CarrierCode_1>CC</CarrierCode_1>
<ServiceClassCode_1>123</ServiceClassCode_1>
<DestinationAirport_1>JFK</DestinationAirport_1>
<FareBaseCode_1>111111</FareBaseCode_1>
<FlightNumber_2>222222</FlightNumber_2>
<TravelDate_2>20120222</TravelDate_2>
<DepartureAirport_2>KEF</DepartureAirport_2>
<CarrierCode_2>CC</CarrierCode_2>
<ServiceClassCode_2>123</ServiceClassCode_2>
<DestinationAirport_2>JFK</DestinationAirport_2>
<FareBaseCode_2>222222</FareBaseCode_2>
<FlightNumber_3>333333</FlightNumber_3>
<TravelDate_3>20120330</TravelDate_3>
<DepartureAirport_3>KEF</DepartureAirport_3>
<CarrierCode_3>CC</CarrierCode_3>
<ServiceClassCode_3>123</ServiceClassCode_3>
<DestinationAirport_3>JFK</DestinationAirport_3>
<FareBaseCode_3>333333</FareBaseCode_3>
<FlightNumber_4>444444</FlightNumber_4>
<TravelDate_4>20120404</TravelDate_4>
<DepartureAirport_4>KEF</DepartureAirport_4>
<CarrierCode_4>CC</CarrierCode_4>
<ServiceClassCode_4>123</ServiceClassCode_4>
<DestinationAirport_4>JFK</DestinationAirport_4>
<FareBaseCode_4>444444</FareBaseCode_4>
<TravelAgencyCode>A7654321</TravelAgencyCode>
<TravelAgencyName>All travel</TravelAgencyName>
<TicketNumber>900.123.222</TicketNumber>
</A1>
</PassengerItineraryData>
</getAuthorization>
Appendix - Action Codes
| Action Code | Explanation | ISO Reply |
|---|---|---|
| 100-199 | Show reason for transaction dismissal by issuer, card pick-up not required. | |
| 000 | Accepted | 00 |
| 100 | Do not honor (Not accepted) | 05 |
| 101 | Expired card | 54 |
| 102 | Suspected card forgery (fraud) | |
| 103 | Merchant call acquirer | 01, 66, 08 |
| 104 | Restricted card | 62 |
| 106 | Allowed PIN retries exceeded | 75, 76 |
| 109 | Merchant not identified | 03 |
| 110 | Invalid amount | 13, 64 |
| 111 | Invalid card number | 14 |
| 112 | PIN required | |
| 116 | Not sufficient funds | 51 |
| 117 | Invalid PIN | 55 |
| 118 | Unknown card | |
| 119 | Transaction not allowed to cardholder | 57 |
| 120 | Transaction not allowed to terminal | 12, 58 |
| 121 | Exceeds limits to withdrawal | 61, 65 |
| 125 | Card not valid | |
| 126 | False PIN block | |
| 129 | Suspected fraud | |
| 130 | Customer Authentication Required | |
| 131 | Invalid Expiration Date | |
| 161 | DCC transaction not allowed to cardholder | |
| 162 | DCC cardholder currency not supported | |
| 163 | DCC exceeds time limit for withdrawal | |
| 164 | DCC transaction not allowed to terminal | |
| 165 | DCC not allowed to merchant | |
| 166 | DCC unknown error | |
| 200-299 | Show reason for transaction dismissal by issuer, card pick-up required. | |
| 200 | No not honor | 04 |
| 201 | Card not valid | 33 |
| 202 | Suspected card forgery (fraud) | |
| 203 | Merchant contact acquirer | 37 |
| 204 | Limited card | 36 |
| 205 | Merchant contact police | |
| 206 | Allowed PIN-retries exceeded | 38 |
| 207 | Special occasion | |
| 208 | Lost card | 41 |
| 209 | Stolen card | 43 |
| 210 | Suspected fraud | |
| 902 | False transaction | 89, 06 |
| 904 | Form error | 30 |
| 907 | Issuer not responding | |
| 908 | Message can not be routed | 15, 80, 81, |
| 909 | System error | 83, 96 |
| 910 | Issuer did not respond | 68 |
| 911 | Issuer timed out | 82 |
| 912 | Issuer not reachable | 91 |
| 913 | Double transaction transmission | 94 |
| 914 | Original transaction can not be traced | |
| 916 | Merchant not found | |
| 950 | No financial record found for detail data | |
| 951 | Batch already closed | |
| 952 | Invalid batch number | |
| 953 | Host timeout | |
| 954 | Batch not closed | |
| 955 | Merchant not active | |
| 956 | Transaction number not unique |
#Demos#
Below are a few demos that can be downloaded to get started.
C# demo
Python demo
PHP demo
FAQ
Frequently Asked Questions
- Is it possible to perform partial refunds (TransType = 3)? Can this happen multiple
times until reaching the total amount authorized?
This is supported, for example- Perform a normal purchase transaction (TransType= 1) with amount 10.
- Then, perform a refund transaction (TransType = 5) with amount 5.
- Finally, perform another refund transaction for the remaining 5.
The sum of the refunds must be equal or lower than the original sale amount.
- Is it possible to send normal purchase transactions(TransType = 1) with less amount than the one specified in the original pre-authorization (TransType = 5) so that the
final authorized amount is the one sent in the normal purchase?
This is supported, for example- Perform a pre-authorize transaction (TransType =5) with amount 10.
- Capture the previous pre-authorization performing a normal purchase transaction
(TransType = 1) with amount 5.
Note that the cardholder will have the withdrawal limit corrected 1-2 days later.
- Has RRN any kind of uniqueness restriction?
RRN has must be size 12 alphanumeric, the last 6 letters cannot be 000000. For reference sake it is recommended to be a sequence with fixed first part, i.e. ACME12345678 - Are batches automatically closed at the same time every day? In that case, could you
tell us the exact time and time zone when this happens? Can this time be configured
or is It fixed?
Default is to have the batch close time fixed, thenit will close at midnight GMT-0 (no daylight changes). It can be controlled by calling party by using the newBatch() command, at execution the old batch is closed and a new one is opened. This is the preferred way to use for custom closure. - Should Refund or Partial Reversal be used?
Refund should be preferred in general, it informs the issuer immediately that the authorization amount will be changed and the creditamount is on the cardholder account in 24-48hours.
Partial Reversal is more suited to specific business cases where there is a high likelihood of an immediate change in the sale amount. An example of this is a vending machine that authorizes for the maximum amount at the beginning then has the sale amount as the actual item buying value. - What is the date format
The gateway uses either yyyymmddhhmmss or yymmddhhmmss depending on functions.
The format is:
yyyy: year in numeric form with four letters, f.ex. 2012 (or 12 if yy) mm: month in numeric format (f.ex. 12 as december) dd: date in numeric format (f.ex. 31) hh: hour in 24 hour numeric format (f.ex. 18) mm: minutes (f.ex. 18) ss: seconds (f.ex. 59)
example
20121231184059 44 - When are batches closed and financial records sent?
Batches are closed at GMT+0 with no daylight savings. All dates at SaltPay are running at GMT+0. Financial records are sent during the night. Merchants can control the batch close time by using newBatch(), the use cases for that are rare and tied to specific merchant segments. - 3D-Secure, when is XID needed and where is VISA ECI
MasterCard uses UCAF and SecurityLevelIndicator, there is no XID in MasterCard SecureCode.
VISA uses CAVV, XID and SecurityLevelIndicator. SecurityLevelIndicator is VISA ECI, the insent value is converted to the equivalent ECIvalue. While CAVV and UCAF have the same function, and SecuityLevel and ECI also have the same function, then the XID is simply a merchant reference number and only used by VISA. - How are credits differentiated/displayed in the settlement response
Credits and deductions are represented with the minus sign in settlement reconciliation data. - What is the preferred timeout?
SaltPay gateway waits for 35 seconds before cancelling requests. A suitable timeout is 40 seconds. - How often can refund be sent for the original transaction?
The cumulative amount of refunds cannot exceed the amount on the original transaction. The refunds can be as many as needed until the sum is equal to the original amount. - What configuration items are used?
As merchants are processed through the business channels they are registered and setup according to business usage. The Business channel will send back
• MerchantId: used in payment gateway to send in authorization request
• MID: used in payment gateway when fetching settlement/fraud/dispute, i.e. reconciliation data
• Terminal information, usually some combination of the following terminal types
Terminal 1 is ecommerce
Terminal 2 is ecommerce with 3D-Secure
Terminal 3 is recurrent
Terminal 4 is MOTO
It simplifies configuration setup if terminal 1 is always ecommerce and 4 is always MOTO etc., but if needed then they can be put in any order.
Not all merchants have all terminals types and would then be sent for example the following
Terminal 1 is ecommerce
Terminal 4 is MOTO
During initial setup a processor number is created that will follow all requests from the merchant, processor, ISO. - Which ActionCodes constitutes errors and which success?
Transactions will only be marked as approved if the returned code from issuer is 000.
There are four ActionCodes that SaltPay does returns, the rest are exclusively from issuers
904: Malformed XML or incorrect data in insent XML
909: System error or network connection to schema is lost
953: Host timeout (can also come from network, but then sporadically)
The difference between 909 and 953 is minimal, if 953 then we will send the request and wait for response, if 909 then we know that the line is down and there is no reason to send the request.
If there are problems, then they start with 953 andthen change to 909 until the we problem is fixed.
Note that 904, 909, 953 can also come from issuers or the card schema network. 904 should always be looked into. - How to find information on authorization if no response is received?
At midnight all open batches are closed, financial records are sent to the card schema and transaction status on financial transactions is set to value 14. getTransactionList() can be called on a regular basis to check on status value and use to reconcile authorization requests with unknown status. - Do the xml elements in a request xml string parameter need to be in a particular
order?
No, the xml elements can be in any order. - Common pitfalls?
• Refunds and cancelAuthorization need the exact DateAndTime + RRN of the original transaction that is being referred.
• ExpireDate in all authorization requests is of the form YYMM 46
• Using cancelAuthorization or Partial Reversal against an original transaction that is in closed batch. After batch is closed the transaction cannot be changed but Refund can be used.
• For historical reasons then the merchantid tag isin some functions and in others.
• Sending in authorization request without TerminalId. The request will go through processing and return 909, the reason being that itis allowed to send in requests without terminal if one terminal has been marked asDefault. That function is not in common use.