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/docs/payment-process-alias for a detailed description about the alias format.

Expiry month of the card. 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 acqAuthorizationCode 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.

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.

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

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

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

Identifier for the product

Mandatory for: BPY BPL BPD

Name of the product

Mandatory for: BPY BPL BPD

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 product

Mandatory for: BPY BPL BPD

Product unit price including VAT

Mandatory for: BPY BPL BPD

Product unit gross price including VAT

Mandatory for: BPY BPL BPD

VAT rate for this product

Article price without VAT

VAT amount for this article

Product unit price without VAT

VAT amount for this unit product

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

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 a 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 for the fee

Name of the fee

AN Category of the product, free text values accepted

Type of the product. Accepted values are GOODS, REBATE, FEE or OTHERPM

Quantity of fee

Fee unit price including VAT

VAT rate for this fee

Fee price without VAT

VAT amount for this fee

Fee unit price without VAT

VAT amount for this unit fee

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

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.

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.

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.

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.

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