Pay by Bank app (Zapp)

REST API

Please note that you can use the REST API documentation also for Wirecard Payment Page v1 LEGACY integration.

Pay by Bank app is a type of Online Bank Transfer.

Countries and Currencies

Countries

Please contact Merchant Support for Countries.

Currencies

GBP

Communication Formats

This table illustrates how Pay by Bank app (PBBA) notifications are encoded and which formats and methods can be used for requests and responses.

Requests/Responses

Format

XML, JSON

Methods

POST

IPN Encodements

Please follow the instructions given at Instant Payment Notification to set up IPN.

Transaction Types

For transaction type details which are not given here look at Transaction Types.

Transaction Type Description Link to sample

debit

receive funds from a consumer’s account to ship the merchandise

See debit samples.

refund-debit

refund an order, because consumer has returned merchandise

Test Credentials

URL(s) Endpoints

For the transaction type debit.

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

For the transaction type refund-debit.

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

Merchant Account ID (MAID)

Please contact merchant support for complete test credentials.

Username

70000-APITEST-AP

Password

qD2wzQ_hrc!8

Secret Key

4a4396df-f78c-44b9-b8a0-b72b108ac465

Additional Test Credentials on PBBA Environment

Merchant Account Name

WD Zapp

PE BCSig

123456

can use credit
(configuration parameter)

true
if false, use: 8a817d99-04bc-4f40-9650-59f726079fa0

mobile endpoint enabled (for Payment SDK purposes)

yes

Workflow
debit
Pay by Bank app Debit Workflow
  1. Consumers select products/services on merchant’s website. (This can happen either with a desktop browser or a mobile device browser. See the PBBA Experience for details).

  2. Consumers select payment method PBBA.

  3. Provider generates a unique code per PBBA payment button.

  4. Consumers log in to the Mobile Banking App (MBA).

  5. Consumers enter the unique payment code.

  6. Consumers confirm payment to their bank.

  7. Consumers have the option to continue with or without PayConnect for the next purchase.

  8. Consumers' bank processes the payment in real-time and sends a notification to provider and merchants.

  9. Consumers' bank displays payment confirmation on MBA.

  10. Merchants redirect consumers to a result page.

refund-request
Pay by Bank app Refund Workflow
  1. Consumers request a refund from merchant.

  2. Merchants send refund request to Wirecard.

  3. WPG requests refund account details of the consumers (transaction type refund-request).

  4. WPG initiates refund using wiretransfer method (take several days).

  5. After confirmation from bank, consumers are refunded (transaction type refund-debit).

Fields
debit with PayConnect

This is faster checkout option without typing the unique 6-digit PBBA code to a mobile banking app. To support the PayConnect feature for Consumer desktop, laptop or tablet based payment journeys, the consumer has an option to link the browser he/she is using to a Mobile Banking App after a successful payment on the device which results in a PayConnect cookie being stored in the consumer’s browser if consent is given.

How it works
  1. Once the consumer has authorised an ECOM Transaction using a PBBA code the Consumer is given the option to enable PayConnect, which links the browser they are using to their mobile banking app.
    PayConnect

  2. On subsequent PBBA transactions from the same browser the Consumer will receive a Push Notification on their linked Mobile device and upon action they automatically invoke their MBA.

  3. The transaction is retrieved by the consumer’s financial institution after the Consumer swipes the Push Notification and logs in to their MBA.

The following elements are mandatory (M), optional (O) or conditional (C) for a request/response/notification. If the respective cell is empty, the field is disregarded or not sent.

Requests that contain capital letters fail.
Do not use capital letters in XML requests.
Field Request Response Notification Type Size Description

browser/user-agent

M

M

M

String

Browser User Agent.

browser/time-zone

M

M

M

String

Browser Time Zone.

browser/screen-resolution

M

M

M

String

Browser Screen.

browser/headers/header/name

O

O

O

String

HTTP Active Header name.

browser/headers/header/value

O

O

O

String

HTTP Active Header value.

browser/cookies/cookie/name

O

O

O

String

Cookie name. Must be pcid.

browser/cookies/cookie/value

O

O

O

String

Cookie value.

browser/cookies/cookie/max-age

O

String

Number of seconds until the cookie expires.

custom-field/[@zapp.out.FIShortName]

O

O

String

Specifies the consumer’s FI Short Name or the Name.
If custom-field/[@zapp.out.CookieStatus] is Y, then FI Short Name must be set.

debit without PayConnect
Field Request Response Notification Type Size Description

merchant-account-id

M

M

M

String

36

Unique identifier for a merchant account

transaction-id

M

M

String

36

The Transaction ID is the unique identifier for a transaction. It is generated by Wirecard.

request-id

M

M

M

String

36

This is the identification number of the request. It has to be unique for each request.

transaction-type

M

M

M

String

22

This is the type for a transaction. Must be debit.

payment-methods/payment-method[@name]

M

M

M

String

9

The name of the Payment Method is zapp.

requested-amount

M

M

M

Decimal

18.3

This is the amount of the transaction. The amount of the decimal place is dependent of the currency. Minimum is 0.01

requested-amount[@currency]

M

M

M

String

3

PBBA supports only GBP.

ip-address

M

M

M

String

IP address of the device.

device/type

M

O

Enum

Type of device which submits the RTP.
Accepted values:
mobile
pc
tablet
other

device/operating-system

M

O

Enum

Operating system used on the device.
Accepted values:
android
ios
windows
windows-mobile
other

custom-field/[@zapp.in.MerchantRtnStrng]

M

O

O

String

Merchant Return String to redirect the Consumer from the Mobile Banking App to the Merchant’s browser or App.

custom-field/[@zapp.in.TxType]

M

O

O

String

Type of Transaction.

custom-field/[@zapp.in.DeliveryType]

M

O

O

String

The delivery type chosen for the delivery of purchased goods.

custom-field/[@zapp.inout.ApTRId]

M

M

String

The human readable Transaction Retrieval ID (Secure Token) generated by PBBA to uniquely identify the related Order.

custom-field/[@zapp.out.CookieStatus]

M

M

Y/N

Cookie status for Payconnect services indicates if the cookie is valid and active.

custom-field/[@zapp.out.SetlmtRtvlId]

M

M

String

The Settlement Retrieval Id must be present if the <RTPType> is IMMEDIATE and must not be present if <RTPType> is DEFERRED.

custom-field/[@zapp.inout.ApTransactionId]

M

M

String

The computer readable Transaction ID generated by PBBA to uniquely identify the Order [a-z A-Z 0-9].

custom-field/[@zapp.out.BRN]

M

M

String

Short term Unique Basket Reference Number provided by PBBA to the Distributor to be conveyed to the consumer in order to retrieve order for payment.

custom-field/[@zapp.out.RtrvlExpiryTimeIntrvl]

O

O

Number

The Retrieval is the time taken from when the consumer hits the Merchant button and sees the transaction within their banking app

custom-field/[@zapp.out.ConfmtnExpiryTimeIntrvl]

M

M

Number

The Confirmation is from the time the consumer sees the transaction within their banking app and presses confirm to submit the payment

api-id

O

O

O

String

A unique identifier assigned for every API.

transaction-state

M

M

String

7

Transaction result status. Should be success or failed

Statuses/status[@code]

M

M

String

Transaction status code (e.g. 201.0000)

statuses/status[@description]

M

M

String

Transaction status description (e.g. 201.0000).

statuses/status[@severity]

M

M

String

Transaction status severity. Should be 'information' for successful transactions, 'error' for failed

completion-time-stamp

M

M

Date time

Timestamp of the get-url transaction

refund-request
Field Request Response Notification Type Size Description

merchant-account-id

M

M

M

String

36

Unique identifier for a merchant account

request-id

M

M

M

String

150

This is the identification number of the request. It has to be unique for each request.

transaction-type

M

M

M

String

22

This is the type for a transaction. Must be Refund-Request

parent-transaction-id

M

M

M

String

36

Transaction-id of debit transaction for which the refund is being done.

payment-methods/payment-method[@name]

M

M

M

String

9

The name of the Payment Method is "zapp".

requested-amount

O

M

M

Decimal

18.3

This is the amount of the transaction. When not defined the whole amount of parent transaction is used.

requested-amount[@currency]

M

M

M

String

3

PBBA supports only GBP.

custom-field/[@zapp.in.RefundReasonType]

M

O

O

String

Used to complete the reason for the Refund, and when applicable will indicate whether a Refund is the result of a Query or Dispute case.

custom-field/[@zapp.in.RefundMethod]

M

O

O

String

The method of Refund that will be used by Wirecard to make the refund payment

custom-field/[@zapp.inout.MerchantRefundRef]

O

O

O

String

Merchant assigned reference for the Refund.

custom-field/[@zapp.in.CaseRefId]

O

O

O

String

Case Reference Id generated by Query/ZDMS to be populated when the Refund is a result of a Query or Dispute. The <zapp.in.CaseRefId> will hold value only when the <zapp.in.RefundReasonType> is DISPUTES

account-holder.last-Name

M

M

M

String

50

This is the last name of the end-consumer.

transaction-state

M

M

String

7

Transaction result status. Should be success or failed

Statuses/status[@code]

M

M

String

Transaction status code (e.g. 201.0000)

statuses/status[@description]

M

M

String

Transaction status description

statuses/status[@severity]

M

M

String

Transaction status severity. Should be 'information' for successful transactions, 'error' for failed

completion-time-stamp

M

M

Date time

Timestamp of the get-url transaction

refund-debit Notification

When refund is finished, the merchant receives refund-debit notification. Notification is send as Base64 Encoded XML message, unless the merchant has different configuration.

Field Notification Type Size Description

merchant-account-id

M

String

36

Unique identifier for a merchant account

request-id

M

String

150

This is the identification number of the request. It has to be unique for each request.

transaction-type

M

String

22

This is the type for a transaction. Must be refund-debit.

parent-transaction-id

M

String

36

Transaction-id of debit transaction for which the refund is being done.

payment-methods/payment-method[@name]

M

String

9

The name of the Payment Method is "zapp".

requested-amount

M

Decimal

18.3

This is the amount of the transaction. When not defined the whole amount of parent transaction is used.

requested-amount[@currency]

M

String

3

PBBA supports only GBP.

custom-field/[@zapp.in.RefundReasonType]

O

String

Used to complete the reason for the Refund, and when applicable will indicate whether a Refund is the result of a Query or Dispute case.

custom-field/[@zapp.in.RefundMethod]

O

String

The method of Refund that will be used by Wirecard to make the refund payment

custom-field/[@zapp.inout.MerchantRefundRef]

O

String

Merchant assigned reference for the Refund.

custom-field/[@zapp.in.CaseRefId]

O

String

Case Reference Id generated by Query/ZDMS to be populated when the Refund is a result of a Query or Dispute.The <zapp.in.CaseRefId> will hold value only when the <zapp.in.RefundReasonType> is DISPUTES

account-holder.last-Name

M

String

50

This is the last name of the end-consumer.

transaction-state

M

String

7

Transaction result status. Should be success or failed

Statuses/status[@code]

M

String

Transaction status code (e.g. 201.0000)

statuses/status[@description]

M

String

Transaction status description

statuses/status[@severity]

M

String

Transaction status severity. Should be 'information' for successful transactions, 'error' for failed

completion-time-stamp

M

Date time

Timestamp of the get-url transaction

Statuses/status[@code]

M

String

Transaction status code (e.g. 201.0000)

statuses/status[@description]

M

String

Transaction status description

statuses/status[@severity]

M

String

Transaction status severity. Should be 'information' for successful transactions, 'error' for failed

ip-address

O

String

merchant-bank-account.iban

O

String

Iban of the bank account that is used to credit the refunded customer.

merchant-bank-account.bic

O

String

Bic of the bank account that is used to credit the refunded customer.

Custom Fields
Field Potential values Description

zapp.in.TxType

BILLPT

Payment is for a Bill

PAYMT

Payment is for retail item

INVOICE

Payment is for an invoice

DONATIONS

Payment is for Donations

zapp.in.DeliveryType

COLLST

Collection from store. The Consumer chooses to collect the goods from store

DELTAD

Delivery to address. The Consumer chooses to have goods delivered to the address specified

DIGDEL

Digital delivery. The Consumer chooses to receive the digital delivery of item purchased

SERVICE

Services provided. For SMB transactions where there is no need for a Delivery address

F2F

Face-to-face transactions. Primarily for use with an SMB transaction.

NONE

No delivery

zapp.in.RefundReasonType

DUPLICATEORDER

Duplicate order. To be used when the Merchant has charged the Consumer twice by accident

GOODSRETURNED

Goods returned. To be used when the Consumer returns goods to the Merchant for a refund

ORDERCANCELLED

Order cancelled. To be used when the Consumer cancels their order

MERCHANTOUTOFSTOCK

Merchant out of stock. To be used by the Merchant when they have charged the Consumer but are out of stock

GOODSNOTRECV

Goods not received. To be used when the goods are not received

LATECONFIRMATION

Late confirmation. To be used when confirmation is late

DISPUTES

Disputes. To be used when there is a dispute

zapp.in.RefundMethod

BACS

To be used if refund would be processed through BACS

CHAPS

To be used if refund would be processed through CHAPS

FPS

To be used if refund would be processed through FPS

OTHER

To be used if refund would be processed through any other method

zapp.in.CaseRefId

any

Reference number that should be included in this message when the Refund is a result of a disputed case.The <zapp.in.CaseRefId> can hold value only when the <zapp.in.RefundReasonType> is DISPUTES

zapp.in.MerchantRtnStrng

URI format

Merchant Return String to redirect the Consumer from the Mobile Banking App to the Merchant’s browser or App

zapp.inout.ApTRId

any

The human readable Transaction Retrieval ID (Secure Token) generated by Pay by Bank app to uniquely identify the related Order

zapp.inout.ApTransactionId

any

The computer readable Transaction ID generated by PBBA to uniquely identify the Order

zapp.inout.MerchantRefundRef

any

Merchant’s system generated reference number for the Refund Transaction. Max length is 35

zapp.out.FIShortName

any

This message field specifies the Consumer’s FI Short Name or the Name

zapp.out.CookieStatus

Y/N

Cookie status for Payconnect services indicates if the cookie is valid and active

zapp.out.BRN

any

Short term Unique Basket Reference Number provided by PBBA to the Distributor to be conveyed to the consumer in order to retrieve order for payment

zapp.out.SetlmtRtvlId

any

Settlement Id which will be mapped to the DSS message. This will be further used by participants for the reconciliation

zapp.out.RefundTransactionId

any

Unique Refund Transaction reference issued by PBBA to log the refund

zapp.out.RefundTRId

any

The Refund Transaction Retrieval Id generated by PBBA

zapp.out.RollNum

any

A reference commonly used by building societies to identify a specific account

zapp.out.DirectConsumerAccountFlag

Y/N

Indicates whether the account details provided are the Consumer’s account or the CFI Holding Account. Y = Consumer account N = Holding account

zapp.out.UniqueRefId

any

Unique Identifier that needs to be included on the bank transfer when the Distributor sends money to the Consumer’s CFI. This will allow the CFI to disperse the money correctly to the end consumer when the funds are received relating to a Refund Transaction

(from EE release 1.130.0) zapp.out.ConfmtnExpiryTimeIntrv

numeric

The Confirmation is from the time the consumer sees the transaction within their banking app and presses confirm to submit the payment

(from EE release 1.130.0) zapp.out.RtrvlExpiryTimeIntrvl

numeric

The Retrieval is the time taken from when the consumer hits the Merchant button and sees the transaction within their banking app

Samples
debit
With PayConnect
debit Request (Successful)
POST https://api-test.wirecard.com/engine/rest/paymentmethods/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/xml;charset=UTF-8
Content-Length: 1307
Host: api-test.wirecard.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Authorization: Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>8a817d99-04bc-4f40-9650-59f726079fa0</merchant-account-id>
   <transaction-id>fb22856d-bd88-4c1c-a212-ab4e32425707</transaction-id>
   <request-id>f1657629-ed60-44c3-8553-642177c049c2</request-id>
   <transaction-type>debit</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2017-11-24T15:02:08.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="information"/>
   </statuses>
   <requested-amount currency="GBP">0.01</requested-amount>
   <ip-address>127.0.0.1</ip-address>
   <notifications>
      <notification url="https://requestb.in/qc51c8qc"/>
   </notifications>
   <custom-fields>
      <custom-field field-name="zapp.in.MerchantRtnStrng" field-value="testVal"/>
      <custom-field field-name="zapp.in.TxType" field-value="PAYMT"/>
      <custom-field field-name="zapp.in.DeliveryType" field-value="DIGDEL"/>
      <custom-field field-name="zapp.inout.ApTransactionId" field-value="293LZ4A1DVB3DY9E7QF77RY00ZARTIEJGCAJG"/>
      <custom-field field-name="zapp.out.FIShortName" field-value="BankToo"/>
      <custom-field field-name="zapp.out.CookieStatus" field-value="Y"/>
      <custom-field field-name="zapp.out.SetlmtRtvlId" field-value="171124000025063686"/>
      <custom-field field-name="zapp.inout.ApTRId" field-value="296515508883024063"/>
      <custom-field field-name="zapp.out.BRN" field-value="NHZDQM"/>
   </custom-fields>
   <payment-methods>
      <payment-method name="zapp"/>
   </payment-methods>
   <api-id>elastic-api</api-id>
   <device>
      <type>mobile</type>
      <operating-system>android</operating-system>
   </device>
   <browser>
      <user-agent>Mozilla/5.0 (Android 7.0; Mobile; rv:54.0) Gecko/54.0 Firefox/54.0</user-agent>
      <time-zone>+01:00</time-zone>
      <screen-resolution>1920*1080</screen-resolution>
      <cookies>
         <cookie>
            <name>pcid</name>
            <value>c9957383-39b5-403f-b4db-650a1555e3bd</value>
         </cookie>
      </cookies>
   </browser>
</payment>
debit Notification (Successful)
<?xml version="1.0" encoding="UTF-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
    <merchant-account-id>8a817d99-04bc-4f40-9650-59f726079fa0</merchant-account-id>
    <transaction-id>ed8f6242-86f7-492e-9d74-81f0375febe5</transaction-id>
    <request-id>f1657629-ed60-44c3-8553-642177c049c2</request-id>
    <transaction-type>debit</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2017-11-24T15:02:16.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="zapp:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="GBP">0.010000</requested-amount>
    <parent-transaction-id>fb22856d-bd88-4c1c-a212-ab4e32425707</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
    <notifications>
        <notification url="https://requestb.in/qc51c8qc"/>
    </notifications>
    <custom-fields>
        <custom-field field-name="zapp.in.MerchantRtnStrng" field-value="testVal"/>
        <custom-field field-name="zapp.in.TxType" field-value="PAYMT"/>
        <custom-field field-name="zapp.in.DeliveryType" field-value="DIGDEL"/>
        <custom-field field-name="zapp.inout.ApTransactionId" field-value="293LZ4A1DVB3DY9E7QF77RY00ZARTIEJGCAJG"/>
        <custom-field field-name="zapp.out.FIShortName" field-value="BankToo"/>
        <custom-field field-name="zapp.out.CookieStatus" field-value="Y"/>
        <custom-field field-name="zapp.out.SetlmtRtvlId" field-value="171124000025063686"/>
        <custom-field field-name="zapp.inout.ApTRId" field-value="296515508883024063"/>
        <custom-field field-name="zapp.out.BRN" field-value="NHZDQM"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="zapp"/>
    </payment-methods>
    <api-id>elastic-api</api-id>
    <device>
        <policy-score>0</policy-score>
    </device>
    <browser>
        <screen-resolution>1920*1080</screen-resolution>
        <cookies>
            <cookie>
                <name>pcid</name>
                <value>e99b925e-2197-4a12-ae38-5a31228b9a3f</value>
                <max-age>4838400</max-age>
            </cookie>
        </cookies>
    </browser>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <DigestValue>+pjrXh6HYEjMPxeepcq8T+nOESfBodOXpiI3O/qnJHo=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>
            fqsJZOKOyeCiHbSPxOzZFlP5O6ezQ4+R3W85Zsix3A5iYkgs1U2mdgRVgJES7XQBsZt5bJWWmlcXFOe+PD6CyhzVlv/tPH8YlUKl6XELvXzkw/FAq0MoKelej2nC1cAuAXEYjrCoouIEYxTRGCYTAffd6c4OwwyEKV7etorUf7ETYG22hxjAdHPL98441PymMN7ktVYOaCdCYz4PCnQAGT4zIgzYcfSON2IVwsbsDo+FnsFwBe97aLZlsjawUc38pL8AWYefmWEVj1H6Wp1qX5AFGyd0Fdn1p3OVlslY+8NL9K2IWSQNeO/UdIiMsUiHHKQvUvm7E2uFh+WjrLxYEYG5GrR8Y4pzcNtnyWL/oOwEyG7udZVt/HKRLXW9AF1sA+Ix9d29vMpJda23ohrfiiCb7hHa21aRJaIHJItg7j2fIzm/Xk6+dYuu2rn41LVeJtqCeX58fdZUz3dE0VOgAvEI5CYZwexN43LjR13nV5zl6Nl3LADEGmGWDqUUIAZz0QZbuN0Armk6ap4wzGkpRSOP1VjLL/5c5+7qo+8o5MPbifl2IElx+cX+d6225R1921y5SMFNsiw9Um6kSjVT8wrZszshllU9aJRbbEmEDAHDLGmyC5ZT9XXxbOqOm2/7KzMhwGtN1EZUX6k/0cde1NVeoC6+lMnmejpKL34p15Q=
        </SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509SubjectName>L=Ascheim,2.5.4.4=#130642617965726e,CN=api-test.wirecard.com,OU=Operations,O=Wirecard Technologies GmbH,C=DE
                </X509SubjectName>
                <X509Certificate>
                    MIIF5DCCBMygAwIBAgICLHQwDQYJKoZIhvcNAQELBQAwWzELMAkGA1UEBhMCREUxETAPBgNVBAoTCFdpcmVjYXJkMTkwNwYDVQQDFDB3aXJlY2FyZC1EUS1NVUMtaW50ZXJuYWwtd2Vic2VydmljZS1pc3N1aW5nQ0FfMDIwHhcNMTcwMTEyMTM1OTI2WhcNMTkwMTEyMTM1OTI2WjCBijELMAkGA1UEBhMCREUxIzAhBgNVBAoTGldpcmVjYXJkIFRlY2hub2xvZ2llcyBHbWJIMRMwEQYDVQQLEwpPcGVyYXRpb25zMR4wHAYDVQQDExVhcGktdGVzdC53aXJlY2FyZC5jb20xDzANBgNVBAQTBkJheWVybjEQMA4GA1UEBxMHQXNjaGVpbTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAKSkExBY8FjRcZdrxOuJF+HZY8+McQaOB8B0E/hTUhoclsF4OJNaMThje7R6w6OYWBMKpssGngHFaZv35rCo5XVUpJmjZa04ytxE72GKO/uP4yIR7ZBXZx42B22MFaJJZTgPRCCFd6jrz906BZ//CmEAmk5gKelfPxfWJgGyTX6xz7I9R/G57E1xNOuEihN0ma5Q2IhD71MPVseFIGazyfGbJD6rYYbeBbOQSGk//TL8sdRCn0BLcm4DH5oqcPxDKzkaBP4ohNkCWsxpLLSyV6Wx0ihT0S1OLVNkEeTvcrYgUk124VyGatwWNUuCBYyOGQSOGqrW8IHmrhjzzT0NQog0/m38lpdqw/eWmt39qhODqSfILUk2Dxv1+W0IRKJCKcJrcTbXEQCuHl+XWY+U2AhinIPNRA0KX2oOgC//inwyKWSGWHdQnaake646R1wHqtoEfCtEcfyaeR+IrMr1rCAA3RZ+MH1J5UlUCWcnxPT0kad6dUwe3Qjq3jK4gaFzYU2yVScX5LVZMlWy2NiGCIvngHQmhArESzxMVvz5METZujfax6hfmiLNRWu0Zqs09Mpxy5zk5m/WRi5izb0uBeCfcA6x9pmjMx8M4OGG5RO2HTXSwLYJTKI47VXNsLLOY+nMFmhj/dkLJ5d3zI7EczToPMRHmHG7EqEdAfbb+oUlAgMBAAGjggGAMIIBfDARBgNVHQ4ECgQIS6wVIA0mJ9IwEwYDVR0jBAwwCoAIQ2weFtQ9BQ4wCwYDVR0PBAQDAgTwMIIBQwYDVR0fBIIBOjCCATYwggEyoIIBLqCCASqGgdVsZGFwOi8vd2lyZWNhcmQubGFuL0NOPXdpcmVjYXJkLURRLU1VQy1pbnRlcm5hbC13ZWJzZXJ2aWNlLWlzc3VpbmdDQV8wMixDTj1DRFAsQ049UHVibGljIEtleSBTZXJ2aWNlcyxDTj1TZXJ2aWNlcyxDTj1Db25maWd1cmF0aW9uLGRjPXdpcmVjYXJkLGRjPWxhbj9jZXJ0aWZpY2F0ZVJldm9jYXRpb25MaXN0P2Jhc2U/b2JqZWN0Q2xhc3M9Q1JMRGlzdHJpYnV0aW9uUG9pbnSGUGh0dHA6Ly9jcmwud2lyZWNhcmQubGFuL0NSTF93aXJlY2FyZC1EUS1NVUMtaW50ZXJuYWwtd2Vic2VydmljZS1pc3N1aW5nQ0FfMDIuY3JsMA0GCSqGSIb3DQEBCwUAA4IBAQAmlUoiEFPRsOjGPb7SYiuJLxqTXCvZQeuXiUydF6FQl/zIpR/zSltaZKK86L+1i7t1C89OyTTXBD9FN6EKmlHo/ulsMn9V2B4zK3lT/NUclST98BmCla4Jzm+roeOHTqlPz3gPRJiPsr3wdvM+FSAJ2MRdv3l77mTE3v3hjsVVMmShR3VwwpxCICl3mpMsSaJZLyJdOHwvnpXs1m9kESwPD3DQ3RAQ/OGa0pPxAkHaauog4DhPvr/nBQnWHd2Us5b/ep7LME9hZ8u3hu/Kc6Vk24c5p3WUOiyaTiw+Ym3QDXl1wBSl9DdM94KbmAAQ5D/FUqyQnSc4TpmYvJ+Iavag
                </X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature>
</payment>
Without PayConnect
debit Request (Successful)
POST https://{rest-api-test-apm-endpoint} HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/xml;charset=UTF-8
Content-Length: 989
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>1b791b2e-4df4-4e08-b2c1-1ae4dd7a2439</merchant-account-id>
    <request-id>0ad04c66-3ccc-4861-a84a-95e3ec3cfa87</request-id>
    <transaction-type>debit</transaction-type>
    <payment-methods>
        <payment-method name="zapp" />
    </payment-methods>
    <requested-amount currency="GBP">1.00</requested-amount>
    <ip-address>127.0.0.1</ip-address>
    <device>
        <type>tablet</type>
        <operating-system>linux</operating-system>
    </device>
    <custom-fields>
        <custom-field field-name="zapp.in.MerchantRtnStrng" field-value="www.myexampleshop/processing" />
        <custom-field field-name="zapp.in.TxType" field-value="PAYMT" />
        <custom-field field-name="zapp.in.DeliveryType" field-value="SERVICE" />
    </custom-fields>
    <api-id>elastic-api</api-id>
</payment>
debit Response (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>1b791b2e-4df4-4e08-b2c1-1ae4dd7a2439</merchant-account-id>
   <transaction-id>3958a84c-391d-4140-b893-62cc49c6107c</transaction-id>
   <request-id>0ad04c66-3ccc-4861-a84a-95e3ec3cfa87</request-id>
   <transaction-type>debit</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2018-02-12T14:32:43.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="information"/>
   </statuses>
   <requested-amount currency="GBP">1.00</requested-amount>
   <ip-address>127.0.0.1</ip-address>
   <custom-fields>
      <custom-field field-name="zapp.in.MerchantRtnStrng" field-value="www.myexampleshop/processing"/>
      <custom-field field-name="zapp.in.TxType" field-value="PAYMT"/>
      <custom-field field-name="zapp.in.DeliveryType" field-value="SERVICE"/>
      <custom-field field-name="zapp.inout.ApTransactionId" field-value="1RIEPHXU0GSB7IZMWMNBCB3EVC1KXCZ0HIH6D"/>
      <custom-field field-name="zapp.out.CookieStatus" field-value="N"/>
      <custom-field field-name="zapp.out.SetlmtRtvlId" field-value="180212000333009124"/>
      <custom-field field-name="zapp.inout.ApTRId" field-value="232207554637899515"/>
      <custom-field field-name="zapp.out.ConfmtnExpiryTimeIntrvl" field-value="150"/>
      <custom-field field-name="zapp.out.BRN" field-value="FRKLLT"/>
      <custom-field field-name="zapp.out.RtrvlExpiryTimeIntrvl" field-value="250"/>
   </custom-fields>
   <payment-methods>
      <payment-method url="https://api-test.wirecard.com/engine/notification/zapp/lightBoxPaymentPage?tkn=232207554637899515&amp;brn=FRKLLT&amp;rtp=250&amp;ctp=150&amp;cks=N&amp;cb=http%3A%2F%2Flocalhost%3A8080%2Fengine%2Fnotification%2Fzapp%2Fcallback%3Ftid%3D3958a84c-391d-4140-b893-62cc49c6107c%26rid%3D0ad04c66-3ccc-4861-a84a-95e3ec3cfa87%26mid%3D1b791b2e-4df4-4e08-b2c1-1ae4dd7a2439%26api%3Delastic-api%26cnc%3Dhttp%253A%252F%252F127.0.0.1%253A8080%252Fshop%252Fcancel.html%26chck%3D5b4145a5d4d27477b62fe3c4d73cefa5b2121019b895628650ebb096f2f570a0&amp;chck=d1636ef97b77a21d2ef8083605471ba9227b7d6cd74d2a105b87f56caaef35e7" name="zapp"/>
   </payment-methods>
   <api-id>elastic-api</api-id>
   <device>
      <type>tablet</type>
      <operating-system>linux</operating-system>
   </device>
</payment>
debit Notification (Successful)
<?xml version="1.0" encoding="UTF-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
    <merchant-account-id>1b791b2e-4df4-4e08-b2c1-1ae4dd7a2439</merchant-account-id>
    <transaction-id>cdc0bf4e-aa46-45a7-af85-7568daf90899</transaction-id>
    <request-id>0ad04c66-3ccc-4861-a84a-95e3ec3cfa87</request-id>
    <transaction-type>debit</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-02-12T14:34:00.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="zapp:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="GBP">1.000000</requested-amount>
    <parent-transaction-id>3958a84c-391d-4140-b893-62cc49c6107c</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
    <custom-fields>
        <custom-field field-name="zapp.in.MerchantRtnStrng" field-value="www.myexampleshop/processing"/>
        <custom-field field-name="zapp.in.TxType" field-value="PAYMT"/>
        <custom-field field-name="zapp.in.DeliveryType" field-value="SERVICE"/>
        <custom-field field-name="zapp.inout.ApTransactionId" field-value="1RIEPHXU0GSB7IZMWMNBCB3EVC1KXCZ0HIH6D"/>
        <custom-field field-name="zapp.out.CookieStatus" field-value="N"/>
        <custom-field field-name="zapp.out.SetlmtRtvlId" field-value="180212000333009124"/>
        <custom-field field-name="zapp.inout.ApTRId" field-value="232207554637899515"/>
        <custom-field field-name="zapp.out.ConfmtnExpiryTimeIntrvl" field-value="150"/>
        <custom-field field-name="zapp.out.BRN" field-value="FRKLLT"/>
        <custom-field field-name="zapp.out.RtrvlExpiryTimeIntrvl" field-value="250"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="zapp"/>
    </payment-methods>
    <api-id>elastic-api</api-id>
    <settlement>
        <gross-amount>1.00</gross-amount>
        <currency>GBP</currency>
    </settlement>
    <device>
        <policy-score>0</policy-score>
        <type>tablet</type>
        <operating-system>linux</operating-system>
    </device>
    <browser>
        <cookies/>
    </browser>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>ncI2ins/pAHk4iDSGJ57akxPAko=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>
            gxYSJqDtEuEcQSCox//Vn4QdtEMEmebus3TF360vaaL+1leyNs8XHWibpKXe9jqeNtz2vRnU3SLcBrNKd9/9j84z6wwwUM3BwCcKmhf6/hQ8yXG5e0zEhLgmA4ituFgiS2YVsOLw3Yyx2HGQNn1hgCGzptpoRe2a9NhNEOk24ayo5Sq6dwGW6Fu85COb1Fx2+DvVJ9woEVtVZWbuhKSlXlXU2WwIgYfeZaKw4fu534cb0coxcZrvKJfiBXNXoswZzFUyziO+r48wphFiPjkuhIXJaQg0pGJvrMt1udZzaAzufGDeJYRg9/zITq7aMv9+zMnRbXa5crlyw2t7OMUCsA==
        </SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509SubjectName>CN=Manoj Sahu,OU=Operations,O=Wirecard Elastic Payments,L=Toronto,ST=ON,C=CA</X509SubjectName>
                <X509Certificate>
                    MIIDcDCCAligAwIBAgIETgQWGTANBgkqhkiG9w0BAQUFADB6MQswCQYDVQQGEwJDQTELMAkGA1UECBMCT04xEDAOBgNVBAcTB1Rvcm9udG8xIjAgBgNVBAoTGVdpcmVjYXJkIEVsYXN0aWMgUGF5bWVudHMxEzARBgNVBAsTCk9wZXJhdGlvbnMxEzARBgNVBAMTCk1hbm9qIFNhaHUwHhcNMTEwNjI0MDQ0NDA5WhcNMTQwMzIwMDQ0NDA5WjB6MQswCQYDVQQGEwJDQTELMAkGA1UECBMCT04xEDAOBgNVBAcTB1Rvcm9udG8xIjAgBgNVBAoTGVdpcmVjYXJkIEVsYXN0aWMgUGF5bWVudHMxEzARBgNVBAsTCk9wZXJhdGlvbnMxEzARBgNVBAMTCk1hbm9qIFNhaHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCc8rTt4N5fNeVzlsRgOXKDE2YUSfJx7xXBozFZ3Vh3XQyy3IpIuEfZz7004k4HeonfTxCNetBvJ9rgNc0Cxrk/euMj3pOUrE9WYN2eAXC0r5pUIAZhIAnSxUSaIF3JKBxf7gDAik5d8RT5HaJV4n5cXJQ/uhAEYU3EGN/74UrD2UsOYD3VBXTJS5VgSi/c3IyLwhDbYIyU6j4fMKyHIlAMGzW7VgKD2pqu6BRysqUVdEEAvW2OmyVqGVyPkm87EiHSMMSar3CvYYxYqBN2KBUjabkvnRWbIzyQuyUyDeUbQmhVQKL0WlMb5ev65m2VjGyDTGL5jfB14rSXRMGzeJ+LAgMBAAEwDQYJKoZIhvcNAQEFBQADggEBADgkuN/e2IFy7JXdbjNJbKBd3HLvFvK87dv8qQ+HK4qfCxYXh6aYhbKHJSA6C2pbOD3HBXoyovZrmk/KqOyUL+unVcR+APjxX4KP25sdkplgmeQ47CWxtKAHZUTtWwAVI/WhsX89SSucBfIS5TJ54e7m02qvGoK8UA/IRbIQ6DZ9hEKV5VQKiMx3ubwwHGXfOWz2fKmeZBuTeY+HiTEH8KCHpfw2j8G+dDgUjlp9LvjVNmJzfNBBk1Si0d/rhXmMzVSKj08tp1sPRK0/sJtJZBzQajpnsZ9NFfoJNdG13AzYwDP3x/QspK0jYn1KZw1qz524VWoQoueR8Xj30A2jntA=
                </X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature>
</payment>
For a failed notification, notice the 'failed' state of the transaction.
refund-request
Refund action triggers a request to return paid funds. Below request supplies consumer’s bank account details kept by Wirecard. These are used to arrange a wiretransfer using BACS scheme (takes several days).
refund-request Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
               <merchant-account-id>2fe4fd54-5ea3-46cf-85ff-c3b86797f821</merchant-account-id>
               <request-id>726bafd6-b17b-4047-a611-b3c8e55925fd</request-id>
               <transaction-type>refund-request</transaction-type>
               <parent-transaction-id>24b115ba-4a2f-44dd-b2e7-d3d4152e56ff</parent-transaction-id>
               <payment-methods>
                              <payment-method name="zapp" />
               </payment-methods>
               <requested-amount currency="GBP">1.00</requested-amount>
                              <custom-fields>
                              <custom-field field-name="zapp.in.RefundReasonType" field-value="LATECONFIRMATION" />
                              <custom-field field-name="zapp.in.RefundMethod" field-value="BACS" />
               </custom-fields>
               <account-holder>
                              <last-name>Doe</last-name>
               </account-holder>
</payment>
refund-request Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction" self="https://api-test.wirecard.com/engine/rest/merchants/70055b24-38f1-4500-a3a8-afac4b1e3249/payments/857059ee-d390-465a-aeb5-49ecdd5a9077">
    <merchant-account-id ref="https://api-test.wirecard.com/engine/rest/config/merchants/70055b24-38f1-4500-a3a8-afac4b1e3249">70055b24-38f1-4500-a3a8-afac4b1e3249</merchant-account-id>
    <transaction-id>857059ee-d390-465a-aeb5-49ecdd5a9077</transaction-id>
    <request-id>726bafd6-b17b-4047-a611-b3c8e55925fh-refund-request</request-id>
    <transaction-type>refund-request</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2017-12-07T09:51:37.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="zapp:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="GBP">1.00</requested-amount>
    <parent-transaction-id>b1ca738d-e20c-4693-a24c-8ac4ad6505c1</parent-transaction-id>
    <account-holder>
        <last-name>Doe</last-name>
    </account-holder>
    <ip-address>127.0.0.1</ip-address>
    <custom-fields>
        <custom-field field-name="zapp.in.RefundReasonType" field-value="LATECONFIRMATION"/>
        <custom-field field-name="zapp.in.RefundMethod" field-value="BACS"/>
        <custom-field field-name="zapp.in.MerchantRtnStrng" field-value="testVal"/>
        <custom-field field-name="zapp.in.TxType" field-value="INVOICE"/>
        <custom-field field-name="zapp.in.DeliveryType" field-value="SERVICE"/>
        <custom-field field-name="zapp.inout.ApTransactionId" field-value="1L60I416J4C1B1SWMLUGLHG02R23KOQ7DR2JG"/>
        <custom-field field-name="zapp.out.CookieStatus" field-value="N"/>
        <custom-field field-name="zapp.out.SetlmtRtvlId" field-value="171207000025075011"/>
        <custom-field field-name="zapp.inout.ApTRId" field-value="209011810157119153"/>
        <custom-field field-name="zapp.out.ConfmtnExpiryTimeIntrvl" field-value="150"/>
        <custom-field field-name="zapp.out.BRN" field-value="HRRNMK"/>
        <custom-field field-name="zapp.out.RtrvlExpiryTimeIntrvl" field-value="250"/>
        <custom-field field-name="zapp.out.DirectConsumerAccountFlag" field-value="N"/>
        <custom-field field-name="zapp.out.RefundTRId" field-value="171207000301060018"/>
        <custom-field field-name="zapp.out.RefundTransactionId" field-value="1ATRTE55HY2A5BG77RQZIW441VP4BMPO28CPF"/>
        <custom-field field-name="zapp.out.UniqueRefId" field-value="nNrTOpgWFtsQvlXhqh"/>
        <custom-field field-name="zapp.out.RollNum" field-value="234567899"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="zapp"/>
    </payment-methods>
    <parent-transaction-amount currency="GBP">1.000000</parent-transaction-amount>
    <api-id>elastic-api</api-id>
</payment>
refund-debit Notification (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
    <merchant-account-id>9f54d887-8a5f-414f-aa53-0be3a90aac5c</merchant-account-id>
    <transaction-id>1e69c428-f947-43f5-878c-3c972e102005</transaction-id>
    <request-id>43b8b510-7486-48cd-8090-35c12b1d818e</request-id>
    <transaction-type>refund-debit</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-01-19T14:15:18.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="zapp:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="GBP">1.000000</requested-amount>
    <parent-transaction-id>1309ca5e-ca80-4530-8566-11165844f733</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
    <notifications>
        <notification url="https://requestb.in/z8qld3z8"/>
    </notifications>
    <custom-fields>
        <custom-field field-name="zapp.in.RefundReasonType" field-value="GOODSRETURNED"/>
        <custom-field field-name="zapp.in.RefundMethod" field-value="FPS"/>
        <custom-field field-name="zapp.in.MerchantRtnStrng" field-value="testVal"/>
        <custom-field field-name="zapp.in.TxType" field-value="INVOICE"/>
        <custom-field field-name="zapp.in.DeliveryType" field-value="SERVICE"/>
        <custom-field field-name="zapp.inout.ApTransactionId" field-value="bFDYPDi8isrEL7tyi8MB3wqIcalccZ8OYlGJv"/>
        <custom-field field-name="zapp.out.CookieStatus" field-value="N"/>
        <custom-field field-name="zapp.out.SetlmtRtvlId" field-value="7vu7dc3Oj9BaVTYrk9"/>
        <custom-field field-name="zapp.inout.ApTRId" field-value="227408776954048749"/>
        <custom-field field-name="zapp.out.ConfmtnExpiryTimeIntrvl" field-value="150"/>
        <custom-field field-name="zapp.out.BRN" field-value="PDwJOX"/>
        <custom-field field-name="zapp.out.RtrvlExpiryTimeIntrvl" field-value="250"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="zapp"/>
    </payment-methods>
    <merchant-bank-account>
        <iban>GB47ESSE40486513304006</iban>
        <bic>ESSEGB2LXXX</bic>
    </merchant-bank-account>
    <api-id>elastic-api</api-id>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>VSZGFt+XRFjv23dAw9GSFtzX8X8=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>
            WMRw9PUR5uoZL8ndToCVA9YKw0LEF6Ww60TXiRfvHpCD5u6CbkfUpvKyUbZ31ehnFUo+kspn4VQRGtzAPdnXlIDqO+KHAD3lNhcmuksIYmbP4woYQ6eKN68D88VtDZ/FmHr4Ws+PGE1j2xkakER3Mf+3AxZ4jhJ/Emz7gKD6SQkakt+plIcRYdDS/RjvAVA4IF+yVDeKFLK8qG9YERktiBRFFnNTM9qH9dzjAvvjB//W4tfyogC4eMkK3YpSF+XTvTHruOdw6y7XachWmGjrJ/J34s2xk4VYgIPsznsZIFJSz8UmBdDsb0XIzAKjDZjj35VJPZJTFd56ANREgcwTIQ==
        </SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509SubjectName>CN=Manoj Sahu,OU=Operations,O=Wirecard Elastic Payments,L=Toronto,ST=ON,C=CA</X509SubjectName>
                <X509Certificate>
                    MIIDcDCCAligAwIBAgIETgQWGTANBgkqhkiG9w0BAQUFADB6MQswCQYDVQQGEwJDQTELMAkGA1UECBMCT04xEDAOBgNVBAcTB1Rvcm9udG8xIjAgBgNVBAoTGVdpcmVjYXJkIEVsYXN0aWMgUGF5bWVudHMxEzARBgNVBAsTCk9wZXJhdGlvbnMxEzARBgNVBAMTCk1hbm9qIFNhaHUwHhcNMTEwNjI0MDQ0NDA5WhcNMTQwMzIwMDQ0NDA5WjB6MQswCQYDVQQGEwJDQTELMAkGA1UECBMCT04xEDAOBgNVBAcTB1Rvcm9udG8xIjAgBgNVBAoTGVdpcmVjYXJkIEVsYXN0aWMgUGF5bWVudHMxEzARBgNVBAsTCk9wZXJhdGlvbnMxEzARBgNVBAMTCk1hbm9qIFNhaHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCc8rTt4N5fNeVzlsRgOXKDE2YUSfJx7xXBozFZ3Vh3XQyy3IpIuEfZz7004k4HeonfTxCNetBvJ9rgNc0Cxrk/euMj3pOUrE9WYN2eAXC0r5pUIAZhIAnSxUSaIF3JKBxf7gDAik5d8RT5HaJV4n5cXJQ/uhAEYU3EGN/74UrD2UsOYD3VBXTJS5VgSi/c3IyLwhDbYIyU6j4fMKyHIlAMGzW7VgKD2pqu6BRysqUVdEEAvW2OmyVqGVyPkm87EiHSMMSar3CvYYxYqBN2KBUjabkvnRWbIzyQuyUyDeUbQmhVQKL0WlMb5ev65m2VjGyDTGL5jfB14rSXRMGzeJ+LAgMBAAEwDQYJKoZIhvcNAQEFBQADggEBADgkuN/e2IFy7JXdbjNJbKBd3HLvFvK87dv8qQ+HK4qfCxYXh6aYhbKHJSA6C2pbOD3HBXoyovZrmk/KqOyUL+unVcR+APjxX4KP25sdkplgmeQ47CWxtKAHZUTtWwAVI/WhsX89SSucBfIS5TJ54e7m02qvGoK8UA/IRbIQ6DZ9hEKV5VQKiMx3ubwwHGXfOWz2fKmeZBuTeY+HiTEH8KCHpfw2j8G+dDgUjlp9LvjVNmJzfNBBk1Si0d/rhXmMzVSKj08tp1sPRK0/sJtJZBzQajpnsZ9NFfoJNdG13AzYwDP3x/QspK0jYn1KZw1qz524VWoQoueR8Xj30A2jntA=
                </X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature>
</payment>

Integration Options

Pay by Bank app (PBBA) can be integrated to multiple options:

  1. Payment Page integration: the merchant wants to offer PBBA on a Payment Page.

  2. REST API integration

    1. Android Merchant Button: The standard PBBA Android Merchant Button with integrated pop-up.

    2. iOS Merchant Button: PBBA iOS Merchant Button library for the iOS Applications.

    3. Web Merchant Button: PBBA Branded and Integrated Web Merchant Button.

  3. PaymentSDK integration: ready made integration into Wirecard PaymentSDK

Integrate with Payment Page
NVP Format of Fields

Mandatory (M), Optional (O) or conditional (C).

Term Request Value Notification Type Size Description

merchant_account_id

M

M

String

36

Unique identifier for a merchant account.

transaction_id

M

String

36

The Transaction ID is the unique identifier for a transaction. It is generated by Wirecard.

request_id

M

M

String

150

This is the identification number of the request. It has to be unique for each request.

transaction_type

M

M

String

22

This is the type for a transaction. Must be debit.

payment_method

O

M

String

9

The name of the Payment Method is zapp.

requested_amount

M

M

Decimal

18.3

This is the amount of the transaction.

The amount of the decimal place is dependent of the currency. Minimum is 0.01

requested_amount_currency

M

M

String

3

Pay by Bank app supports only GBP.

ip_address

M

M

String

IP address of the device.

device_type

O

Enum

Type of device which submits the RTP. Enum types: mobile - mobile phone, pc - PC or laptop, tablet, other.

If not provided it will be resolved automatically. It is recommended to let the Payment Page resolve this field automatically.

device_os

O

Enum

Operating system used on the device. Enum types: android - Android, ios - Apple IOS, windows - Windows, windows-mobile - Windows Mobile OS, other.

If not provided it will be resolved automatically. It is recommended to let the Payment Page resolve this field automatically.

field_name_n[1-10]

O

String

Text used to name the transaction custom field. Possible values for n can be in the range from 1 to 10

field_value_n[1-10]

O

String

Used with a key, the content used to define the value of the transaction custom field. Possible values for n can be in the range from 1 to 10

field_name_1

M

zapp.in.TxType

O

String

Type of Transaction.

field_value_1

M

O

String

Type of Transaction.

field_name_2

M

zapp.in.DeliveryType

O

String

The delivery type chosen for the delivery of purchased goods.

field_value_2

M

O

String

The delivery type chosen for the delivery of purchased goods.

field_name_3

O

zapp.in.MerchantRtnStrng

O

String

Merchant Return String to redirect the Consumer from the Mobile Banking App to the Merchant’s browser or App.

field_value_3

O

O

String

Merchant Return String to redirect the Consumer from the Mobile Banking App to the Merchant’s browser or App.

If not provided it will be resolved automatically. It is recommended to let the Payment Page resolve this field automatically.

transaction_state

M

String

7

Transaction result status. Should be success, cancel or failed.

status_code_n

M

String

Transaction status code (e.g. 201.0000).

status_description_n

M

String

Transaction status description.

status_severity_n

M

String

Transaction status severity. Should be information for successful transactions, error for failed.

completion_time_stamp

M

Date time

Timestamp of the get-url transaction

Integrate with HPP

If merchant’s configuration results in skipping the screen where a customer can choose from different payment methods (only when merchant has only Pay by Bank app method configured), then merchant needs to send these 3 parameters in request:

Obsolete since Release 1.140.0. (JUN 2018); Merchant doesn’t need to provide following information any longer, HPP supplies it automatically.
Term Request Notification Type Description

browser_screen_resolution

M

M

String

Browser Screen

browser_time_zone

M

String

Browser Time Zone

browser_user_agent

M

String

Browser User Agent

Sample NVP Request
<html>
<head>
    <!-- ... -->
    <script src="http://api-test.wirecard.com/engine/hpp/paymentPageLoader.js" type="text/javascript"></script>
    <!-- ... -->
</head>
<body>
    <!-- ... -->
    <input id="wirecard_pay_btn" type="button" onclick="pay()" value="Pay Now"/>
    <script type="text/javascript">
        function pay() {
            var requestedData = {
                "merchant_account_id": "ea44f407-aec0-478f-87c8-7d73fef3431e",
                "ip_address": "127.0.0.1",
                "payment_method": "",
                "requested_amount": "8.00",
                "requested_amount_currency": "GBP",
                "transaction_type": "debit",
                "shipping_first_name": "",
                "shipping_last_name": "",
                "shipping_street1": "",
                "shipping_street2": "",
                "shipping_city": "",
                "shipping_state": "",
                "shipping_country": "",
                "shipping_postal_code": "",
                "is_request_signature_v1": "true",
                // shop plugin analytics data (optional)
                "shop_system_name": "Shopware",
                "shop_system_version": "5.2",
                "plugin_name": "Shopware HPP Plugin of Wirecard",
                "plugin_version": "1.3.4",
                "integration_type": "HPP",
                "request_id": "5978d97a-8b7c-103b-21e6-adecd617209c",
                "request_time_stamp": "20171201174525",
                "first_name": "John",
                "last_name": "Doe",
                "email": "john@doe.com",
                "phone": "+421123456789",
                "street1": "Mullerstrasse 137",
                "street2": "",
                "city": "Berlin",
                "state": "Berlin",
                "country": "DE",
                "postal_code": "13353",
                "redirect_url": "",
                "date_of_birth": "01-01-1980",
                "order_number": "order123456",
                "order_detail": "",
                "locale": "",
                "psp_name": "",
                "custom_css_url": "",
                "field_name_1": "zapp.in.TxType",
                "field_value_1": "PAYMT",
                "field_name_2": "zapp.in.DeliveryType",
                "field_value_2": "DELTAD",
                "orderItems[0].id": "itm01",
                "orderItems[0].name": "Notebook",
                "orderItems[0].description": "Simple Notebook",
                "orderItems[0].articleNumber": "123",
                "orderItems[0].amount.value": "1",
                "orderItems[0].amount.currency": "GBP",
                "orderItems[0].taxRate": "19",
                "orderItems[0].quantity": "2",
                "orderItems[1].id": "shipping",
                "orderItems[1].name": "SHIPPING & HANDLING",
                "orderItems[1].description": "",
                "orderItems[1].articleNumber": "shipping",
                "orderItems[1].amount.value": "6",
                "orderItems[1].amount.currency": "GBP",
                "orderItems[1].quantity": "1",
                "orderItems[1].taxRate": "19",
                /* You need to calculate a proper signature on your server to
                demonstrate the authenticity of every request. Please consult
                the merchant documentation for the details.
                NEVER SHARE YOUR SECRET IN THE BROWSER! */
                "request_signature": "de50672d26590cacec7664b09be563aefaadbdb2942b8f2b881dfb50103ac958"
            }
            WirecardPaymentPage.embeddedPay(requestedData);
        }
    </script>
    <!-- ... -->
</body>
</html>
Branded and Integrated Android Merchant Button

This section describes the PBBA Android Merchant Button library for Android applications.

Map secureToken and brn elements to the Wirecard Payment Gateway

Mandatory (M), Optional (O) or conditional (C).

Parameter name Parameter description Parameter source

activity

The fragment activity in the Merchant App.

Provided by the Merchant App

secureToken

The unique token that identifies the payment request.

Term

custom-field/[@zapp.inout.ApTRId]

Request

Response

M

Notification

M

Type

String

Size

Description

The human readable Transaction Retrieval ID (Secure Token) generated by Pay by Bank app to uniquely identify the related Order.

Example

<custom-field field-name=zapp.inout.ApTRId field-value=242509503999812313/>

brn

The six character code that identifies the payment request for the duration of retrieval timeout.

Term

custom-field/[@zapp.out.BRN]

Request

Response

M

Notification

M

Type

String

Size

Description

Short term Unique Basket Reference Number provided by Pay by Bank app to the Distributor to be conveyed to the consumer in order to retrieve order for payment.

Example

<custom-field field-name=zapp.out.BRN

field-value=FRPSXS/>

callback

PBBACallback implementation that receives callback events. Please see section 'How to implement the Popup Callback' for sample code on how to implement the callback.

Provided by the Merchant App

API to invoke the PBBA enabled CFI App
Parameter name Parameter description Parameter source

activity

The activity in the merchant app.

Provided by the Merchant App

secureToken

The unique token that identifies the payment request.

Term

custom-field/[@zapp.inout.ApTRId]

Request

Response

M

Notification

M

Type

String

Size

Description

The human readable Transaction Retrieval ID (Secure Token) generated by Pay by Bank app to uniquely identify the related Order.

Example

<custom-field field-name=zapp.inout.ApTRId

field-value=242509503999812313/>

Branded and Integrated iOS Merchant Button

This section refers to the PBBA branded iOS Merchant Button and PBBA integrated iOS Merchant Button documentation.

This section describes the PBBA iOS Merchant Button library for iOS applications.

Map secureToken and brn elements to the Wirecard Payment Gateway

Mandatory (M), Optional (O) or conditional (C).

Parameter name Parameter description Parameter source

popupPresenter

The instance of view controller which will present the PBBA Popup.

Provided by the Merchant App.

secureToken

The unique token that identifies the payment request.

Term

custom-field/[@zapp.inout.ApTRId]

Request

Response

M

Notification

M

Type

String

Size

Description

The human readable Transaction Retrieval ID (Secure Token), generated by Pay by Bank app to uniquely identify the related Order.

Example

<custom-field field-name=zapp.inout.ApTRId

field-value=242509503999812313/>

brn

The six character code that identifies the payment request for the duration of retrieval timeout.

Term

custom-field/[@zapp.out.BRN]

Request

Response

M

Notification

M

Type

String

Size

Description

Short term Unique Basket Reference Number provided by Pay by Bank app to the Distributor to be conveyed to the consumer in order to retrieve order for payment.

Example

<custom-field field-name=zapp.out.BRN

field-value=FRPSXS/>

popupDelegate

The PBBA Popup delegate instance.

Provided by the Merchant App.

API to invoke the PBBA enabled CFI App
Parameter name Parameter description Parameter source

secureToken

The unique token that identifies the payment request.

Term

custom-field/[@zapp.inout.ApTRId]

Request

Response

M

Notification

M

Type

String

Size

Description

The human readable Transaction Retrieval ID (Secure Token) by Pay by Bank app to uniquely identify the related Order.

Example

<custom-field field-name=zapp.inout.ApTRId

field-value=242509503999812313/>

Branded and Integrated Web Merchant Button

This section refers to the PBBA branded Web Merchant Button and PBBA integrated Web Merchant Button documentation.

Functional Overview

The PBBA Web Merchant Button enables Merchants to use PBBA as a payment method. Written in JavaScript, the Web Merchant Button library can be included on any Website by following a few steps.

Interaction of the M-COMM Journey Components

This sequence diagram shows the interaction between the components of the M-COMM journey.

image
Interaction of the E-COMM Journey Components

This sequence diagram shows the interaction between the components of the E-COMM journey.

image
Interaction of the E-COMM PayConnect Journey Components

This sequence diagram shows the interaction between the components of the E-COMM PayConnect journey.

image
PBBA Branded and Integrated Web Merchant Button Setup
Implementing Web Merchant Button Methods

When you want to implement the Pay method with the branded Web Merchant Button or any other method with the branded Web Merchant Button or integrated Web Merchant Button you must map the PBBAmerchantRequestToPayObject elements to the Wirecard Payment Gateway.

merchantRequestToPayObject.payConnectID maps to:

Term Request Response Notification Type Size Description

browser/cookies/cookie/name

O

O

O

String

Cookie name. Must be pcid.

browser/cookies/cookie/value

O

O

O

String

Cookie value

Mandatory (M), Optional (O) or conditional (C).

Example
<browser>
   <user-agent>Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36</user-agent>
   <time-zone>+02:00</time-zone>
   <screen-resolution>1920*1080</screen-resolution>
   <cookies>
       <cookie>
           <name>pcid</name>
            <value>54f90a00-1468-4cf9-948c-837dea2f8c8a</value>
       </cookie>
   </cookies>
</browser>
The Pay method - for Successful Request To Pay Response

When merchants want to post Request To Pay, they need to call the Wirecard Payment Gateway’s endpoint https://api-test.wirecard.com/engine/rest/paymentmethods/ with transaction type debit following the PBBA REST API documentation.

When posting a Request To Pay you must map the PBBA merchantRequestToPayResponseObject elements to the Wirecard Payment Gateway.

merchantRequestToPayResponseObject.secureToken is a unique token that identifies a Request To Pay. It maps to:

Term Request Response Notification Type Size Description

custom-field/[@zapp.inout.ApTRId]

M

M

String

The human readable transaction-retrieval-id (Secure Token) generated by PBBA to uniquely identify the related order.

Mandatory (M), optional (O) or conditional (C).

Example

<custom-field field-name=zapp.inout.ApTRId field-value=242509503999812313/>

merchantRequestToPayResponseObject.pbbaCode is a six character code, that identifies a Request to Pay for the duration of retrieval timeout period. It maps to:

Term Request Response Notification Type Size Description

custom-field/[@zapp.out.BRN]

M

M

String

Short term unique basket reference number provided by PBBA to the distributor to be conveyed to the consumer in order to retrieve order for payment.

Mandatory (M), Optional (O) or conditional (C).

Example

<custom-field field-name=zapp.out.BRN field-value=FRPSXS/>

merchantRequestToPayResponseObject.retrievalTimeOutPeriod specifies the time window from the generation of PBBA Code/secureToken to the expiry of PBBA Code/secureToken, this is used by the get status (Notify method) polling engine. It maps to:

Term Request Response Notification Type Size Description

custom-field/[@zapp.out.RtrvlExpiryTimeIntrvl]

O

O

Number

The retrieval is the time taken from when the consumer hits the Merchant button and sees the transaction within their banking app.

Mandatory (M), optional (O) or conditional (C).

Example

<custom-field field-name=zapp.out.RtrvlExpiryTimeIntrvl field-value=250/>

merchantRequestToPayResponseObject.confirmationTimeoutPeriod is the allowed period of time after the retrieval is complete and before a payment status is received, the polling continues for total sum of retrieval and confirmation timeout period. It maps to:

Term Request Response Notification Type Size Description

custom-field/[@zapp.out.ConfmtnExpiryTimeIntrvl]

M

M

Number

The Confirmation is from the time the consumer sees the transaction within their banking app and presses Confirm to submit the payment.

Mandatory (M), optional (O) or conditional (C).

Example

<custom-field field-name=zapp.out.ConfmtnExpiryTimeIntrvl field-value=150/>

merchantRequestToPayResponseObject.cookieSentStatus is used in the PayConnect journey only. The field confirms, if a payment notification was sent out to consumer. The popup component of the button shows the appropriate popup, based on this flag. It maps to:

Term Request Response Notification Type Size Description

custom-field/[@zapp.out.CookieStatus]

M

M

C

String

Cookie status for Payconnect services indicates, if the cookie is valid and active. Value can be either Y or N.

Mandatory (M), optional (O) or conditional (C).

Example

<custom-field field-name=zapp.out.CookieStatus field-value=N/>

merchantRequestToPayResponseObject.bankName is used in the PayConnect Journey only. The Popup informs that a push notification is sent out, it also displays the CFI name. It maps to:

Term Request Response Notification Type Size Description

custom-field/[@zapp.out.FIShortName]

O

O

String

This message field specifies the Consumer’s FI Short Name or the Name. If custom-field/[@zapp.out.CookieStatus] is Y, then FI Short Name must be set.

Mandatory (M), optional (O) or conditional (C).

Example

<custom-field field-name=zapp.out.FIShortName field-value=R3PITCFI/>

The Notify method

When a transaction is confirmed/declined by the consumer, merchants receive a payment notification.

If you want to use the Notify method, you must map the PBBA merchantGetPaymentStatusObject elements to the Wirecard Payment Gateway.

merchantGetPaymentStatusObject.payConnectID is used in the PayConnect Journey. When the consumer has opted for PayConnect, then this ID will be passed back in the payment status response and should be sent in the browser element. It maps to:

Term Request Response Notification Type Size Description

browser/cookies/cookie/name

O

O

O

String

Cookie name. Must be pcid.

browser/cookies/cookie/value

O

O

O

String

Cookie value.

Mandatory (M), optional (O) or conditional (C).

Example
<browser>
    <screen-resolution>1920*1080</screen-resolution>
    <cookies>
        <cookie>
            <name>pcid</name>
            <value>cd186b6e-05fa-48ef-9df1-17346fd64d42</value>
            <max-age>4838400</max-age>
            <secure>false</secure>
            <http-only>false</http-only>
        </cookie>
    </cookies>
</browser>

merchantGetPaymentStatusObject.cookieExpiryDays defines the number of days the PayConnectID based cookies is valid for. It maps to:

Term Request Response Notification Type Size Description

browser/cookies/cookie/max-age

O

O

String

Cookie max age. Number of seconds until the cookie expires. Must be converted to days.

Mandatory (M), optional (O) or conditional (C).

Example
<browser>
    <screen-resolution>1920*1080</screen-resolution>
    <cookies>
        <cookie>
            <name>pcid</name>
            <value>cd186b6e-05fa-48ef-9df1-17346fd64d42</value>
            <max-age>4838400</max-age>
            <secure>false</secure>
            <http-only>false</http-only>
        </cookie>
    </cookies>
</browser>