Datatrans API reference

Unique transaction identifier

Unique Merchant Identifier (assigned by Datatrans during signup). Depending on your integration you might receive multiple merchantIds. For example: One for your mobile application and one for your web shop. Get a merchantId now and start using the APIs.

The merchants reference number. It should be unique for each transaction.

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00. If the payment method supports it, amount=0 can be submitted when using either Redirect Mode or Lightbox Mode and the user should only be registered (saving the users payment method to a profile for example). Use <amount>0</amount> for validating an existing alias.

3 letter ISO-4217 character code. For example CHF, USD

The sign parameter to be submitted with each request. Refer to Request signing for more details.

The aliasCC received with a Payment or Registration. Refere to https://docs.datatrans.ch/v1.0.1/docs/payment-process-alias for a detailed description about the alias format.

Expiry month of the card. For example 1 or 01 for January.

Expiry year of the card

Authorization response code. 01 for a successful authorization, 02 for a successful authorization without liability shift.

Response code 02 is returned, if the issuer doesn’t claim liability. In case of a charge back the merchants will have the liability. These transactions are declined by default. If you would like to accept transactions with a response code 02, please modify the configuration in the Webadmin Tool

Human readable response message.

Deprecated, use uppTransactionId instead.

Authorization code returned by credit card issuing bank (length depending on payment method)

Masked credit card number. Returned only for Credit cards and if aliasCC was used for the request or uppReturnMaskedCC was used with either Redirect Mode or Lightbox Mode. The maskedCC can be safely stored and might be used for later displaying it to the user.

If available, ISO 3166-1 alpha-3 country code of the cardholders issuer bank.

The error code for the transaction.

Error response message text if available. For example: declined

Error detail if available. For example: Declined

Contains the error code sent by the acquirer

Date when authorization request was received.

Time when tha authorization request was received.

05 if it was a debit. 06 for a credit. This corresponds to the <transtype> parameter.

The amount already settled. Can be lower than the amount of the authorization partial settlements are used.

Defines if the transaction should be closed for further settlements. Switch the value from no to yes in your last settlement request. This parameter is only required for deferred settlements, when you want to close a transaction before settling the full amount.

The ID of your sub-merchant as defined by your acquirer.

Your fee for your marketplace offerings that you want to take out of each operation. The acquiring fees will be automatically deducted from this amount.

Currency code for fee amount.

yes to returns an Alias if the payment method supports it. The value of the alias will be in the aliasCC parameter.

This parameter specifies the language (language code) in which the payment page should be presented to the cardholder. The following ISO-639-1 two letter language codes are supported:

If the payment is started within an iframe or when using the Lightbox Mode, use value _top. This ensures a proper browser flow for payment methods who need a redirect.

If the payment is started within an iframe or when using the Lightbox Mode use _top if the callback URLs should be opened full screen when payment returns from a 3rd party (for example 3D).

forceRedirect when displaying the redirect mode inside an iframe. It makes sure that no (X) button on the top right of the payment page is getting displayed. Additionally a click on the back button will redirect to the merchants cancel url.

Submit return as the parameter value in the request, and it will be replaced in the response with the real 3D status:

yes – requests the return of the masked credit card number to the merchant in field maskedCC. Example value: 424242xxxxxx4242

This parameter only works for Credit cards

This parameter represents the URL of the merchant’s web shop, where the consumer should be redirected to after a successful transaction

This parameter represents the URL of the merchant’s web shop, application, where the consumer should be redirected to after cancelling the transaction.

This parameter represents the URL of the merchant’s web shop, application, where the consumer should be redirected to after a failed transaction

For web transactions using one of the Integrations:

yes, if the sent customer details parameters should be stored in the Webadmin Tool, or return (only available for PayPal) – if address details should be returned from PayPal to the merchant.

For server to server authorizations the Common parameters are placed inside the <uppCustomerDetails> element.

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

Identifier for a customer

Mandatory for: INT

Title of the customer

Name of the customer

First name of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

Last name of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

Either P (=person/B2C) or C (=company/B2B)

Mandatory for: ACC INT DVI

Steet name of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

Second street name of the customer

City of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

ISO 3166-1 alpha-3 country code of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI

Postal code of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

State of the customer

Phone number of the customer

Mandatory for: ACC BPY BPL BPD SWB

Fax number of the customer

E-Mail address of the customer

BPY BPL BPD SWB MFX MFA INT

Gender of the customer. Possible values: female, male

Mandatory for: ACC BPY BPL BPD MFX MFA

Customer date of birth. Format: dd.mm.yyyy or yyyy-mm-dd

Mandatory for: ACC BPY BPL BPD SWB MFX MFA INT

Language of customer. Possible values: en, de, fr, it

Mandatory for: ACC INT

Possible values: EXISTING, REGISTERING, GUEST

Mandatory for:

BPY BPL BPD

Type of customer subscription. For example: test

Mandatory for: SWB

The ip address of the customer.

Identifier for the product

Mandatory for: BPY BPL BPD

Name of the product

Mandatory for: BPY BPL BPD KLN

Category of the product, free text values accepted.

Other information related to the product

Type of the product. Possible values vary per payment method. Refer to the corresponding payment method chapter.

Quantity of similar products on the current invoice line item

Mandatory for: BPY BPL BPD KLN

Line item price including VAT. If the current invoice line has multiple similar products then uppArticle_1_Price = uppArticle_1_Quantity * uppArticle_1_SingleArticlePrice

Mandatory for: BPY BPL BPD KLN

Product unit gross price including VAT

Mandatory for: BPY BPL BPD

VAT rate for this product

Mandatory for: KLN

Line item price without VAT

VAT amount for this line item

Mandatory for: KLN

Product unit price including VAT

Product unit price without VAT

If yes all shipping parameters are mandatory except uppShippingStreet2 remains optional.

Title of the recipient

First name of recipient

Mandatory for: BPY BPL BPD

Last name of recipient

Mandatory for: BPY BPL BPD

Street address of recipient

Mandatory for: BPY BPL BPD

Possible values vary per payment method. Refer to the corresponding payment method chapter.

Postal code of recipient

Mandatory for: BPY BPL BPD

City of recipient

Mandatory for: BPY BPL BPD

ISO 3166-1 alpha-3 country code of the recipient

Mandatory for: BPY BPL BPD

Phone number of recipient

Cell phone number of recipient

Value of all items in the basket, in smallest available unit.

Mandatory for: BPY BPL BPD

Gross value of all items in the basket, in smallest available unit.

Mandatory for: BPY BPL BPD

For example: DHL, Express

Mandatory for: BPY BPL BPD

The email address of the recipient

If yes all billing parameters are mandatory except uppBillingStreet2 remains optional.

Title of the recipient of the bill

First name of the recipient of the bill

Last name of the recipient of the bill

Street address of the recipient of the bill

Possible values vary per payment method. Refer to the corresponding payment method chapter.

Phone number of the recipient of the bill

The email address of the recipient of the bill

Postal code of the recipient of the bill

City of the recipient of the bill

ISO 3166-1 alpha-3 country code of the the recipient of the bill

Use SCN if only a pre-screening request should be done. When using NOA, a screening and authorization request will be done.

Name of the company

Legal form of the company

Either INVOICE or INSTALLMENT

The authorizationId received from an initial credit check request. Use <reqtype>SCN</reqtype> to do only a credit check and not an actual payment.

base64 encoded values of attachments in the following format:

Amount in the basket payed by coupon or other payment instruments.

Possible values: 3x3, 4x12, 12x12

Possible values: EMAIL, PRINT, INSURANCE, MERCHANT

true or false whether the uppCustomerStreet will be splitted into streetName and streetNumber

Accarda reference number, mainly useful for B2B orders where the company doing the order might have their own ID to identify the invoice later on within their own systems.

Identifier of the fee

Name of the fee

Category of the fee, free text values are accepted

Type of the fee. Accepted values are GOODS, REBATE, FEE or OTHERPM but recommended value is FEE

Quantity of similar fees in the current invoice line item

Fee total price including VAT

VAT rate for this fee

Fee total price without VAT

VAT amount for this fee

Fee unit price including VAT

Fee unit price without VAT

XML representation of the Accarda eshop basket containing the total amount and the products. This parameter is base64 encoded and can be used for future partial credit requests.

XML representation of the instalment plan returned by the successfulcredit decision check. This parameter is base64 encoded.

XML representation of the info element returned by the successful transaction. This parameter is base64 encoded. For example:

When doing a pre-screening request with reqtype=SCN:

When doing a credit request:

Possible values: PROVIDER, MERCHANT

Possible values: OK, NOK

Possible values: OK, NOK

The authorization id returned by the successful credit decision check

If installments are available. Check the sub_pmethod parameter.

If invoice is available. Check the sub_pmethod parameter.

The token received from Apple when integrating the Buy with Apple Pay button. Needs to be wrapped in a CDATA element:

The rebate amount

The rebate gross amount.

Name of the account holder.

Bank code of the account holders bank.

Invoice reference number

The bank name.

Account holders IBAN. For example DE2501200000TEST000000000003.

Use SCN if only a pre-screening request should be done. When using NOA, a screening and authorization request will be done.

Name of the company

Register number of the company

One of

Identification of the customer in the shop.

One of

Can be true or false to indicate that customer has confirmed the email address to the merchant. It has a default value of false if missing.

Customer information for credit check.

Customer information for credit check.

Can be used in case when client operates different legally separated stores / points of sale.

Number value from 1 to 20 indicate repayment schedule, is used in combination with Payment Methods and defined per client configuration.

Which party should take the risk. Possible values: IJ (Intrum Justitia) or CLIENT.

Wheter or not to send a paper invoice. Possible values: YES and NO.

A list of custom data fields. It can accept up to 10 entries

Installment amount of the first installment.

Indication if merchant is having verified documents from client request.

Used values

Verified document issuer.

Verified document number.

List of the available payment options returned by a successful credit decision check. Those Byjuno payment methods can be submitted with the sub_pmethod parameter. For example:

Possible values: yes and no

Byjuno has support for partial settlement. If one of the partial settlement requests will send closeTransaction=true it will close the partial settlement process, no other settlement requests will be accepted.

Identification of the customer’s (buyer’s) financial institution by a BIC

Structured remittance identifier "Zahlungsreferenz"

This value is displayed on the external Swisscom webpage, in the notification SMS, in the Swisscom customer center and on the consumer‘s bill.

If parameter is not submitted, the value from parameter refno will be taken. If parameter is submitted without value, an error will occure on Swisscom webpage. Allowed characters: A-Za-z0-9_-

Title of the content/product. Will be displayed on external webpage from Swisscom. Allowed characters: A-Za-z0-9_-

Description of the content/product. Will be displayed on external webpage page from Swisscom. Allowed charcters: Everything except ‘<’, ‘>’, ‘&’

BIC (8 or 11-digits)

Purpose

Bank code

Bank name

payment processor transaction ID

UATP cardnumber

expiry year of UATP card (format: YYYY)

expiry month of UATP card (format: MM)

BIC (8 or 11-digits)

Purpose

Additional information field which is shown on the payment form (label)

Additional information field which is shown on the payment form (text)

Bank code

Bank name

payment processor transaction ID

Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID)

Age verification result code

UATP cardnumber

expiry year of UATP card (format: YYYY)

expiry month of UATP card (format: MM)

The data received from Google when integrating the Buy with Google Pay button. Needs to be wrapped in a CDATA element:

The data above is truncated. Make sure to submit the whole cryptogram received by Google.

Register number of the company

Language to use with the Klarna payment page after redirect

Country of the customer

Type of the line item. It should be one of the following values [ physical | discount | shipping_fee | sales_tax | digital | gift_card ]

Name of the event, e.g. "Fancy Singer"

Name of the company arranging the event, e.g. "Happy Parties Ltd."

Category or type of venue, "Pop"

Name of the venue, "Song Arena"

Street name of the arena.

Postal code of the arena.

City of the arena.

Country of the arena.

Start time of the event, e.g. 2020-01-24 15:00

End time of the event, e.g. 2020-01-24 18:00

Tickets are digitally checked when enetering the venue.

[ true | false ]

Ticket delivery menthod

[ pick_up | email | post | phone ]

The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.

Name of the affiliate that originated the purchase. If none, leave blank.

Name of the product on subscription, e.g. "Contact lenses"

Start time of the subscription, e.g. 2020-01-24 15:00

End time of the subscription, e.g. 2020-01-24 18:00

Info whether the subscription will be auto renewed upon expiry.

Name of the affiliate that originated the purchase. If none, leave blank.

Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"

Registration time of the customer account, e.g. 2020-01-24 15:00

Last modified time of the customer account, e.g. 2020-01-24 18:00

Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"

Whether the customer has paid before or not

Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"

Type of the line item. It should be one of the following values

[ card | direct banking | non klarna credit | sms | other ]

Total number of successful purchases

Total amount of successful purchases (local currency), e.g. 1234.00

Date of last paid purchase, e.g. 2020-01-24 15:00

Date of the first paid purchase, e.g. 2020-01-24 15:00

Trip booking number, e.g. VH67899

Hotel itinerary data, one per hotel stay

Insurance data

Passengers data

Name of the affiliate that originated the purchase. If none, leave blank.

Name of hotel

Hotel street address

Hotel postal code

Hotel city

Hotel country

Start date of the hotel reservation, e.g. 2020-01-24 15:00

End date of the hotel reservation, e.g. 2020-01-24 15:00

Number of rooms on the reservation

Array with passenger ids, e.g. 1,2,3,4

Ticket delivery method should be one of the following values [pick_up | email | post | phone]

The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.

Hotel price in local currency

Hotel class

Name of the insurance company

Type of insurance should be one of the following values [ cancellation | travel | cancellation_travel | bankruptcy ]

Insurance price in local currency

Id of the passenger

Mr, Mrs, Ms or blank if under 12 years

First name of the passenger

Last name of the passenger

Name of the company.

For B2B, parameters uppCustomerFirstName, uppCustomerLastName, uppCustomerGender and uppCustomerBirthDate are optional.

The virtual card number of the customer. Returned to the success URL when submitting returnVirtualCardno=yes with MFX or MFA.

The parameters that are necessary to offer paying on installments to the customers are the following: <installmentNumber>, <installmentAmount>, <installmentFees>, <installmentInterests>. We will send those fields in the response if the field <installmentType> is i.e. 4in12, which means 4 payments in 12 months. Merchant need special agreement for this option with MFGroup.

This parameters gives the merchant the possibility to take the risk for some transactions, especially when the <amount> is higher than the <mfaAvailableCredit> of the customer. Please consider, that the merchant has to be authorized by MFGroup first, to do such kind of transactions.

Will be forwarded as parameter ExternalReference2 to MFGroup

Will be forwarded as parameter ExternalReference3 to MFGroup

Whether an invoice should be sent together with the delivery. If yes, the response parameter ESRData will contain the necessary data to print the payment slip.

The credit of the customer currently available for purchases.

The maximum credit available for this customer

The customers reference within the MFGroup system which can be saved and used to retrieve the customer and his account for further purchases; to be submitted with all subsequent transactions of the same customer.

contains the result of the credit check, which is None in case of success

Response code from MFGroup

Returned in case of error. Possible values are: * unknown address - customer is unknown or was not found * other - request was declined because of an unknown error.

The number of installments the customer has to pay.

The amount of each installment the customer has to pay (including installment fees and installment interest), amount in the smallest available unit.

The amount of fees included in the installments, amount in the smallest available unit.

The amount of interests included in the installments, amount in the smallest available unit.

XML element - contains all needed data to correctly print the payment slip.

XML element - contains data for direct bank connection.

Username of registered MDP customer.

needed if a payment shall be processed as an alias payment

Alias (if requested by merchant and confirmed by the customer) when using useAlias=yes

Migros Banks unique transaction reference number

This parameter is identifying the customer, i.e. 2 transactions made from the same customer must have the same paysafecardMerchantClientId. You can use the unique ID of your customer as registered within your database, for example. If you are using the e-mail address or any other personal information, please encrypt it.

Header item: Total amount of all items (L_AMT0 * L_QTY0) + (L_AMT1 * L_QTY1) + …​

Header item: Total tax amount in cents (L_TAXAMT0 * L_QTY0) + (L_TAXAMT1 * L_QTY1) + …​

Header item: total shipping fees excluding tax.

Line item: Item name - For example L_NAME1=Beer

Line item: price per items in cents

Line item: article number

Line item: description

TLine item: number of items

Line item: tax amount

The final amount parameter is calculated from ITEMAMT + SHIPPINGAMT + TAXAMT.

yes if the Customer details (if submitted) should be forwarded to PayPal. The following Customer details parameters are mandatory so that PayPal will display (uppDisplayShippingDetails=yes) them:

Regulates whether the shipping details are displayed or not. (Note: uppForwardCustomerDetails and uppDisplayShippingDetails should be set to no if the shipping details should not be shown on the PayPal page.

This parameter will be returned only if the PayPal transaction is in a pending status. Pending means that the transaction couldn’t be confirmed by PayPal. Make sure to contact PayPal directly in this case.

The data received from Samsung when integrating the Pay with Samsung Pay button. Needs to be wrapped in a CDATA element:

Use SCN if only a pre-screening request should be done. When using NOA, a screening and authorization request will be done.

Name of the company

Either P (=person/B2C) or C (=company/B2B)

Total VAT amount for this purchase

Total discount amount, use positive value