Surcharging

Surcharging is a feature for Wirecard Payment Page v1 (HPP and EPP) and REST API. Aimed at merchants who would like to charge additional fees for certain types of payments, this feature guarantees transparency on surcharge rates for consumers.

In Australia, this feature complies with the RBA’s surcharging standards.

Surcharge rates (given as either a fixed amount or percentage) vary depending on region, card type indicator, card type and payment method.

  • Region:

    • Domestic

    • International

  • Card type indicator:

    • Credit

    • Debit

    • Prepaid

  • Card type:

    • Visa

    • Mastercard

    • Amex

    • JCB

    • UPI

  • Alternative payment method (if required):

Merchant Account Setup

To enable this feature, contact merchant support.

Your account must be set up as follows:

  • Your merchant account must be configured to enable surcharging.

  • Your country must be defined in your merchant account.

  • Surcharge rates must be configured by region, card type indicator, card type, and payment method.

Surcharge Amount

The surcharge amount is the amount added to the original transaction amount (price of a good or service). It is calculated based on the respective surcharge rates. Depending on the originial transaction amount, the surcharge amount varies. The sum of the surcharge amount and the original transaction amount results in the final amount payable.

Partial Refund/Capture is not allowed for surcharge transactions. Surcharge transactions must be refunded/captured in full.

The surcharge amount can be determined in two ways:

  1. Auto-calculate the surcharge amount based on the configured surcharge rates.

  2. Calculate the surcharge amount yourself and include the value directly as part of the purchase request.

    Including the <surcharge-amount> as part of the purchase request overwrites your merchant account configuration.

Workflow

Depending on how the surcharge amount is determined, the workflow varies.

  1. If you decide to auto-calculate the surcharge amount based on the configured surcharge rates:

    • send a purchase request without including a predefined surcharge amount.

    • send a calculate-fee request and retrieve the surcharge amount from the response first, then

    • insert the retrieved value in the purchase request and send the request thereafter.

  2. If you decide to calculate the surcharge amount yourself, include the value directly as part of the purchase request (Wirecard Payment Page v1 and REST API).

Below, we provide calculate-fee and purchase samples for REST API.

Test Credentials

URL (Endpoint)

https://api-test.wirecard.com/engine/rest/payments/

Merchant Account ID (MAID)

66f26bcf-e032-44ec-ad6b-d363a261c375

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key

b37e50b3-6827-4bb2-9f3e-276b2e319b7b

Fields

Mandatory (M) or optional (O).

Field Cardinality Datatype Size Description

merchant-account-id

M

String

36

Unique identifier assigned to every merchant account.

request-id

M

String

32

Unique identifier assigned to every request (by the merchant). Used when searching for or referencing it later. {{$guid}} serves as a placeholder for a random request-id. Allowed characters:
a - z
0 - 9
-_

transaction-type

M

String

n/a

Requested transaction type.
For a complete list of transaction types, please see Appendix B: Transaction Types.

requested-amount

M

Decimal

18,2

Full amount that is requested/contested in a transaction. The number of decimals depends on the currency.

requested-amount@currency

M

String

3

Currency in which a transaction is received and processed.

account-holder/last-name

M

String

32

Last name of the account holder.

account-holder/email

O

String

64

Email address of the account holder.

card/account-number

M - or Card Token

String

36

Embossed or encoded number that identifies the card issuer to which a transaction is to be routed and the account to which it is to be charged unless specific instructions indicate otherwise. In case of credit card, this is the primary account number.

card/expiration-month

M - or Card Token

Number

2

2-digit representation of the expiration month of the account-number.

card/expiration-year

M - or Card Token

Number

4

4-digit representation of the expiration year of the account-number.

card/card-security-code

Depending on merchant account settings

String

4

Security feature for credit or debit card transactions providing increased protection against credit card or debit card fraud. The card security code is located on the back of Mastercard, Visa and Discover credit or debit cards and is typically a separate group of 3 digits towards the right of the signature strip. On American Express cards, the card security code is a printed, not embossed, group of four digits on the front towards the right.

card/card-type

M

String

15

Card scheme accepted by the processing system. This includes physically issued cards.

surcharge/surcharge-amount

O

Decimal

18,6

Amount added to the original transaction amount based on the respective surcharge rates. The number of decimals depends on the currency.

payment-methods/payment-method@name

O

String

256

Name of the payment method.

descriptor

O

String

n/a

Description of the transaction for account holder’s bank statement purposes.

merchant-account-id@ref

M

String

n/a

Reference URL to the merchant account. Can be used to retrieve merchant account details over a browser. This information is returned in the response only.

transaction-id

M

String

36

Unique identifier assigned to every transaction (by Wirecard). Used when searching for or referencing it later. This information is returned in the response only.

transaction-state

M

String

n/a

Current transaction state.

Possible values:

  • in-progress

  • success

  • failed

Typically, a transaction starts with state in-progress and finishes with state either success or failed. This information is returned in the response only.

completion-time-stamp

M

Timestamp

n/a

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ssZ (ISO).

This information is returned in the response only.

statuses/status@code

M

String

12

Status code of the status message. This is primarily used in conjunction with the transaction state to determine the exact details of the status of the transaction. This information is returned in the response only.

statuses/status@description

M

String

256

Description of the transaction status message. This information is returned in the response only.

statuses/status@severity

M

String

20

Definition of the status message.
Possible values:

  • information

  • warning

  • error

card-token/token-id

O

String

16

Unique identifier assigned to every card token. This is a surrogate value for the primary account number. This information is returned in the response only.

card-token/masked-account-number

M

String

16

Masked account number. This information is returned in the response only.

authorization-code

O

String

24

Code generated by the card issuing bank as proof that the transaction request was acknowledged or declined. This information is returned in the response only.

api-id

O

String

36

Identifier for the currently used API. This information is returned in the response only.

original-requested-amount

O

Decimal

18,6

Full amount that is requested/contested in the original transaction. The number of decimals depends on the currency. This information is returned in the response only.

original-requested-amount@currency

O

String

3

Currency in which the original transaction is received and processed. This information is returned in the response only.

Samples

calculate-fee
XML Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>66f26bcf-e032-44ec-ad6b-d363a261c375</merchant-account-id>
  <request-id>{{$guid}}</request-id>
    <transaction-type>calculate-fee</transaction-type>
    <requested-amount currency="AUD">1000</requested-amount>
    <payment-methods>
        <payment-method name="creditcard" />
    </payment-methods>
    <card>
        <account-number>4012000300001003</account-number>
        <expiration-month>01</expiration-month>
        <expiration-year>2023</expiration-year>
        <card-security-code>003</card-security-code>
        <card-type>visa</card-type>
    </card>
</payment>
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/66f26bcf-e032-44ec-ad6b-d363a261c375">66f26bcf-e032-44ec-ad6b-d363a261c375</merchant-account-id>
    <request-id>b8fd83d1-73e5-45cd-a60d-44568937c978</request-id>
    <transaction-type>calculate-fee</transaction-type>
    <requested-amount currency="AUD">1000</requested-amount>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <api-id>elastic-api</api-id>
    <surcharge>
        <surcharge-amount currency="AUD">0</surcharge-amount>
        <original-requested-amount currency="AUD">1000</original-requested-amount>
    </surcharge>
</payment>
purchase
XML Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>66f26bcf-e032-44ec-ad6b-d363a261c375</merchant-account-id>
  <request-id>{{$guid}}</request-id>
  <transaction-type>purchase</transaction-type>
  <requested-amount currency="AUD">10.000000</requested-amount>
  <account-holder>
    <last-name>Doe</last-name>
    <email>john.doe@test.com</email>
  </account-holder>
  <card>
    <account-number>4012000300001003</account-number>
    <expiration-month>01</expiration-month>
    <expiration-year>2023</expiration-year>
    <card-security-code>123</card-security-code>
    <card-type>visa</card-type>
  </card>
  <surcharge>
    <surcharge-amount>1.500000</surcharge-amount>
  </surcharge>
  <payment-methods>
    <payment-method name="creditcard"/>
  </payment-methods>
</payment>
XML Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/66f26bcf-e032-44ec-ad6b-d363a261c375/payments/cf237d14-a96f-486b-ab9b-8ec59f9211c6">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/66f26bcf-e032-44ec-ad6b-d363a261c375">66f26bcf-e032-44ec-ad6b-d363a261c375</merchant-account-id>
    <transaction-id>cf237d14-a96f-486b-ab9b-8ec59f9211c6</transaction-id>
    <request-id>78656c6e-d09c-4228-a807-497dd4351b1e</request-id>
    <transaction-type>purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2019-08-07T06:19:24.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="AUD">11.500000</requested-amount>
    <account-holder>
        <last-name>Doe</last-name>
        <email>john.doe@test.com</email>
    </account-holder>
    <card-token>
        <token-id>4304509873471003</token-id>
        <masked-account-number>401200******1003</masked-account-number>
    </card-token>
    <descriptor></descriptor>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <authorization-code>352420</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>00000031756D9706</provider-account-id>
    <surcharge>
        <surcharge-amount>1.500000</surcharge-amount>
        <original-requested-amount currency="AUD">10.000000</original-requested-amount>
    </surcharge>
</payment>
Custom URL: