Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

When requesting card payments via 

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePartner-Name
PageWithExcerptWording
hosted forms the complexity of 3-D Secure is completely removed from the merchant implementation.

From a merchant point of view the sequence itself does not differ between 3DS authenticated and non-authenticated payments though 3DS requires consideration of additional data elements in the request and response.

Note
titleNotice about Cookie-/Session Handling

Please note that some browsers might block necessary cookies when returning to Your shop. Here you will find additial information and different solution approaches.

Simplified Sequence Diagram

Multiexcerpt
MultiExcerptNameSimplified Sequence Diagram
shouldDisplayInlineCommentsInIncludesfalse


Table of Contents


Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameLink_CookieSessionHandling
DisableCachingtrue
PageWithExcerptReuse API

Payment Request

To retrieve a

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePartner-Name
PageWithExcerptWording
card form please submit the following data elements via HTTP POST request method to
Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNameBaseURL
PageWithExcerptWording
payssl.aspx.

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1625489336430_-2082385216
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0


Multiexcerpt
MultiExcerptNamepayment_request


Determines the type and time of capture.

Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1625489336432_-1792890293
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*


DE

KeyFormatCNDDescriptionBeschreibung
1

MerchantID

ans..30

M

Merchant identifier assigned by

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePartner-Name
PageWithExcerptWording
HändlerID, die von
Multiexcerpt include
SpaceWithExcerpt
MultiExcerptNamePartner-Name
PageWithExcerpt
DE:
Wording
vergeben wird

2

MsgVer

ans..5

M

Message version.

Values accepted

  • 2.0

Message-Version.

Zulässiger Wert:

  • 2.0
3

TransID

ans..64

M

Transaction identifier supplied by the merchant. Shall be unique for each paymentTransaktions-ID des Händlers, die für jede Zahlung eindeutig sein muss
4

RefNr

ans..

4

RefNr

ans..30

O

Merchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePartner-Name
PageWithExcerptWording
settlement file (CTSF) we cannot add the additional payment data.

5

Amount

n..

Eindeutige Referenznummer des Händlers, welche als Auszahlungsreferenz in der entsprechenden Acquirer EPA-Datei angegeben wird. Bitte beachten Sie, ohne die Übergabe einer eigenen Auszahlungsreferenz können Sie die EPA-Transaktionen nicht zuordnen, zusätzlich kann das

Multiexcerpt include
SpaceWithExcerptDE
MultiExcerptNamePartner-Name
PageWithExcerptDE:Wording
Settlement File (CTSF) auch nicht zusätzlich angereichert werden.

5

Amount

n..10

M

Transaction amount in it smallest unit of the submission currencyBetrag in der kleinsten Währungseinheit (z.B. EUR Cent)
6

Currency

a3

M

ISO 4217 three-letter currency codeWährungskürzel, drei Zeichen DIN / ISO 4217
7

Capture

ans..6

O

Capture ModeDescription
AUTOCapturing immediately after authorisation (default value).
MANUALCapturing made by the merchant. Capture is normally initiated at time of delivery.
<Number>Delay in hours until the capture (whole number; 1 to 696).

Bestimmt Art und Zeitpunkt der Buchung (engl. Capture).

BuchungsartBeschreibung
AUTOBuchung sofort nach Autorisierung (Standardwert).
MANUALBuchung erfolgt durch den Händler - in der Regel die Buchung zum Zeitpunkt der Warenauslieferung bzw. Leistungserbringung.
<Zahl>Verzögerung in Stunden bis zur Buchung (ganze Zahl; 1 bis 696).
8

billingDescriptor

ans..22

O

A descriptor to be printed on a cardholder’s statement. Please also refer to the additional comments made elswhere for more information about rules and regulations.Eine Bezeichnung, die auf dem Kontoauszug des Karteninhbaers gedruckt wird. Beachten Sie bitte auch die zusätzliche Hinweise an anderer Stelle für weitere Informationen über Regeln und Vorschriften.
9

OrderDesc

ans..768

O

Order descriptionBeschreibung der gekauften Waren, Einzelpreise etc.
10

AccVerify

a3

O

Indicator to request an account verification (aka zero value authorization). If an account verification is requested the submitted amount will be optional and ignored for the actual payment transaction (e.g. authorization).

Values accepted

  • Yes

Indikator für Anforderung einer Kontoverifizierung (alias Nullwert-Authorisierung). Bei einer angeforderten Kontoverifizierung ist der übermittelte Betrag optional und wird für die tatsächliche Zahlungstransaktion ignoriert (z.B. Autorisierung).

Zulässiger Wert:

  • Yes
11

threeDSPolicy

JSON

O

Object specifying authentication policies and excemption handling strategiesObjekt, das Authentisierungs-Richtlinien und Vorgaben für die Ausnahmenbehandlung festlegt
12

priorAuthenticationInfo

JSON

O

Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transactionDas Objekt Prior Transaction Authentication Information enthält optionale Informationen über eine Authentisierung eines 3DS-Karteninhabers, die vor der aktuellen Transaktion erfolgt ist
13

accountInfo

JSON

O

The account information contains optional information about the customer account with the merchantDas Objekt Kontoinformationen enthält optionale Informationen über das Kundenkonto beim Händler
14

billToCustomer

JSON

C

The customer that is getting billed for the goods and / or services. Required for EMV 3DS unless market or regional mandate restricts sending this information.

Der Kunde, dem die Waren und / oder Dienstleistungen in Rechnung gestellt werden. Für EMV 3DS erforderlich, sofern nicht Markt- oder Regionalmandate die Übermittlung dieser Informationen beschränken.
15

shipToCustomer

JSON

C

The customer that the goods and / or services are sent to. Required if different from billToCustomer.Der Kunde, an den die Waren und / oder Dienstleistungen gesendet werden. Erforderlich, falls von billToCustomer abweichend.
16

billingAddress

JSON

C

Billing address. Required for EMV 3DS (if available) unless market or regional mandate restricts sending this information.Rechnungsadresse. For EMV 3DS erforderlich (falls verfügbar), sofern nicht Markt- oder Regionalmandate die Übermittlung dieser Informationen beschränken.
17

shippingAddress

JSON

C

Shipping address. If different from billingAddress, required for EMV 3DS (if available) unless market or regional mandate restricts sending this information.Lieferadresse. Falls von billingAddress abweichend; für EMV 3DS erforderlich (falls verfügbar), sofern nicht Markt- oder Regionalmandate die Übermittlung dieser Informationen beschränken.
18

credentialOnFile

JSON

C

Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer. Required if applicable.Objekt, das Art und Reihe von Transaktionen mittels Zahlungskonto-Zugangsdaten festlegt (z.B. Kontonummer oder Zahlungs-Token), die bei einem Händler für die Verarbeitung zukünftiger Einkäufe für einen Kunden gespeichert sind. Erforderlich, falls zutreffend.
19

merchantRiskIndicator

JSON

O

The Merchant Risk Indicator contains optional information about the specific purchase by the customer.

If no shippingAddress is present it is strongly recommended to populate the shippingAddressIndicator property with an appropriate value such as shipToBillingAddress, digitalGoods or noShipment.

Der Händler-Risikoindikator enthält optionale Informationen über den bestimmten Einkauf des Kunden.

Falls shippingAddress nicht vorhanden ist, ist es dringend empfohlen, das Merkmal shippingAddressIndicator mit einem entsprechenden Wert wie shipToBillingAddress, digitalGoods oder noShipment auszufüllen.

20subMerchantPFJSONOObject specifying SubMerchant (Payment Facilitator) details.Objekt, das die Details des SubMerchant (Payment Facilitator) angibt
21

URLNotify

an..256

M

A FQDN URL to submit the final payment result (HTTP POST). The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values please use the parameter UserData.

Eine FQDN URL zur Übermittlung des finalen Zahlungsergebnisses (HTTP POST). Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData.
22

URLSuccess

an..256

M

A FQDN URL for redirection of the client in case the payment was processed succefully (HTTP POST). The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values please use the parameter UserData.

Eine FQDN URL zur Weiterleitung des Kunden für den Fall, dass die Zahlung erfolgreich war (HTTP POST). Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData.
23

URLFailure

an..256

M

A FQDN URL for redirection of the client in case the payment could not be processed succefully (HTTP POST). The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values  please use the parameter UserData.

Eine FQDN URL zur Weiterleitung des Kunden für den Fall, dass die Zahlung nicht erfolgreich war (HTTP POST). Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData.
24

UserData

ans..1024

O

If specified at request,

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Kurz
PageWithExcerptWording
forwards the parameter with the payment result to the shop

Wenn beim Aufruf angegeben, übergibt das

Multiexcerpt include
SpaceWithExcerptDE
MultiExcerptNamePlatform-Kurz
PageWithExcerptDE:Wording
den Parameter mit dem Zahlungsergebnis an den Shop

25

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithmHash Message Authentication Code (HMAC) mit SHA-256-Algorithmus

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
will return an HTML document in the response body representing the requested card form. The form may be included in the merchant checkout page or used as a standalone page to redirect the cardholder to.

Multiexcerpt
MultiExcerptNamepaysslForm
shouldDisplayInlineCommentsInIncludesfalse

Image Removed

Cardholder authentication and payment authorization will take place once the the cardholder entered all required card details and submitted the form data to

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
.

Note: In case you are using your own templates (Corporate Payment Page), please make sure you include Cardholder name on your custom template. Cardholder name is mapped to

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Kurz
PageWithExcerptWording
API parameter "CreditCardHolder". Cardholder name field must not contain any special characters and must have minimal length of 2 characters and maximum length of 45 characters.

When the payment is completed

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
will send a notification to the merchant server (i.e. URLNotify) and redirect the browser to the URLSuccess resepctively to the URLFailure.

The blowfish encrypted data elements as listed in the following table are transferred via HTTP POST request method to the URLNotify and URLSuccess/URLFailure.

NoteNotice: Please note that the call of URLSuccess or URLFailure takes place with a GET in case of fallback to 3-D Secure 1.0. Therefore your systems should be able to receive parameters both via GET and via POST

10

M

Transaction amount in it smallest unit of the submission currency
6

Currency

a3

M

ISO 4217 three-letter currency code
7

Capture

ans..6

O

Determines the type and time of capture.

Capture ModeDescription
AUTOCapturing immediately after authorisation (default value).
MANUALCapturing made by the merchant. Capture is normally initiated at time of delivery.
<Number>Delay in hours until the capture (whole number; 1 to 696).


8

billingDescriptor

ans..22

O

A descriptor to be printed on a cardholder’s statement. Please also refer to the additional comments made elswhere for more information about rules and regulations.
9

OrderDesc

ans..768

O

Order description
10

AccVerify

a3

O

Indicator to request an account verification (aka zero value authorization). If an account verification is requested the submitted amount will be optional and ignored for the actual payment transaction (e.g. authorization).

Values accepted

  • Yes
11

threeDSPolicy

JSON

O

Object specifying authentication policies and excemption handling strategies
12

priorAuthenticationInfo

JSON

O

Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transaction
13

accountInfo

JSON

O

The account information contains optional information about the customer account with the merchant
14

billToCustomer

JSON

C

The customer that is getting billed for the goods and / or services. Required for EMV 3DS unless market or regional mandate restricts sending this information.

15

shipToCustomer

JSON

C

The customer that the goods and / or services are sent to. Required if different from billToCustomer.
16

billingAddress

JSON

C

Billing address. Required for EMV 3DS (if available) unless market or regional mandate restricts sending this information.
17

shippingAddress

JSON

C

Shipping address. If different from billingAddress, required for EMV 3DS (if available) unless market or regional mandate restricts sending this information.
18

credentialOnFile

JSON

C

Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer. Required if applicable.
19

merchantRiskIndicator

JSON

O

The Merchant Risk Indicator contains optional information about the specific purchase by the customer.

If no shippingAddress is present it is strongly recommended to populate the shippingAddressIndicator property with an appropriate value such as shipToBillingAddress, digitalGoods or noShipment.

20subMerchantPFJSONOObject specifying SubMerchant (Payment Facilitator) details.

URLNotify

ans..256

M

A FQDN URL for redirection of the client in case the payment was processed succefully (HTTP POST).

Complete URL which Platform calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserData parameter instead.

(info) Common notes:

  • We recommend to use parameter "response=encrypted" to get an encrypted response by Platform
  • However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

URLSuccess

ans..256

M

A FQDN URL for redirection of the client in case the payment was processed succefully (HTTP POST).

Complete URL which calls up Platform if payment has been successful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Platform and shop, please use the parameter UserData.

(info) Common notes:

  • We recommend to use parameter "response=encrypted" to get an encrypted response by Platform
  • However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

URLFailure

ans..256

M

A FQDN URL for redirection of the client in case the payment was processed succefully (HTTP POST).

Complete URL which calls up Platform if payment has been unsuccessful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Platform and shop, please use the parameter UserData.

(info) Common notes:

  • We recommend to use parameter "response=encrypted" to get an encrypted response by Platform
  • However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.
24

UserData

ans..1024

O

If specified at request,

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Kurz
PageWithExcerptWording
forwards the parameter with the payment result to the shop

25

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

Response

a7

O

Status response sent by Platform to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter.


ReqId

ans..32

O

To avoid double payments / actions, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction / action is submitted again with the same ReqID, Axepta Platform will not carry out the payment or new action, but will just return the status of the original transaction / action. Please note that the Axepta Platform must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.


Plain

ans..50

O

A value to be set by the merchant to return some information unencrypted, e.g. the MID


Custom

ans..1024

O

The merchant can submit several values separated by | which are returned unencrypted and separated by &.

Custom=session=123|id=456 will change in the answer to Session=123&id=456


expirationTime

ans..19

O

timestamp for the end time of the transaction processing, specified in UTC.

Format: YYYY-MM-ddTHH:mm:ss


CustomField[n]

ans..50

O
Field that can be used individually by the merchant. Presently 14 fields from CustomField1 to CustomField14 are supported.





Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
will return an HTML document in the response body representing the requested card form. The form may be included in the merchant checkout page or used as a standalone page to redirect the cardholder to.

Multiexcerpt
MultiExcerptNamepaysslForm
shouldDisplayInlineCommentsInIncludesfalse

Image Added


Cardholder authentication and payment authorization will take place once the the cardholder entered all required card details and submitted the form data to

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
.

Note: In case you are using your own templates (Corporate Payment Page), please make sure you include Cardholder name on your custom template. Cardholder name is mapped to

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Kurz
PageWithExcerptWording
API parameter "CreditCardHolder". Cardholder name field must not contain any special characters and must have minimal length of 2 characters and maximum length of 45 characters.

When the payment is completed

Multiexcerpt include
SpaceWithExcerptEN
MultiExcerptNamePlatform-Name
PageWithExcerptWording
will send a notification to the merchant server (i.e. URLNotify) and redirect the browser to the URLSuccess resepctively to the URLFailure.


The blowfish encrypted data elements as listed in the following table are transferred via HTTP POST request method to the URLNotify and URLSuccess/URLFailure.

Note
Notice: Please note that the call of URLSuccess or URLFailure takes place with a GET in case of fallback to 3-D Secure 1.0. Therefore your systems should be able to receive parameters both via GET and via POST.



The following table gives the result parameters which Axepta Platform transmits to URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:

(info) pls. be prepared to receive additional parameters at any time and do not check the order of parameters

(info) the key (e.g. MerchantId, RefNr) should not be checked case-sentive



MID

ans..30

M

MerchantID, assigned by BNP

PayID

an32

M

ID assigned by Platform for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Platform

Code

an8

M

Error code according to Platform Response Codes (A4 Error codes)

Description

ans..1024

M
Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

TransID

ans..64

M

TransactionID which should be unique for each payment

Please note for some connections the different formats that are given within the specific parameters.

Status

a..50

M

OK or AUTHORIZED (URLSuccess) as well as FAILED (URLFailure)

MAC

an64

M
Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HashMAC-Authentication.
UserData

ans..1024

O

If specified at request, Platform forwards the parameter with the payment result to the shop.

MaskedPan

an..19

OC

Masked card number 6X4. If you want to receive the parameter MaskedPan, please contact Axepta Helpdesk, which can activate the return.

TransID

ans..64

M

TransactionID which should be unique for each payment

Please note for some connections the different formats that are given within the specific parameters.

CAVV

ans..40

OC

In the case of 3-D Secure with Authentication Hosting (only 3-D request without authorisation): Cardholder Authentication Validation Value: Contains the digital signature for authentication with the ACS of the card issuing bank.

Plain

ans..50

O

A value to be set by the merchant to return some information unencrypted, e.g. the MID

Custom

ans..1024

O

The merchant can submit several values separated by | which are returned unencrypted and separated by &.

Custom=session=123|id=456 will change in the answer to Session=123&id=456

CustomField[n]

ans..50

O
Field that can be used individually by the merchant. Presently 14 fields from CustomField1 to CustomField14 are supported.


HTTP POST to URLSuccess / URLFailure / URLNotify

Table Filter
defaultBeschreibung
isFirstTimeEnterfalse
hideColumnstrue
sparkNameSparkline
hidePanetrue
datepatterndd M yy
id1625489403900_-1676195126
worklog365|5|8|y w d h m|y w d h m
isORAND
separatorPoint (.)
order0


Multiexcerpt
MultiExcerptNamehttp_post


Table Transformer
dateFormatdd M yy
export-wordfalse
show-sourcefalse
export-csvfalse
id1625489403902_195677908
transposefalse
worklog365|5|8|y w d h m|y w d h m
separator.
export-pdffalse
sqlSELECT * FROM T*

Table Excerpt Include
statictrue
nameMID
pageMID
typepage

KeyFormatCNDDescriptionBeschreibung

MsgVer

ans..5

M

Message version.

Accepted values:

  • 2.0

Message-Version.

Zulässiger Wert:

  • 2.0

Table Excerpt Include
statictrue
namePayID
pagePayID
typepage

Table Excerpt Include
statictrue
nameXID
pageXID
typepage

Table Excerpt Include
statictrue
nameTransID
pageTransID
typepage

KeyFormatCNDDescriptionBeschreibung

schemeReferenceID

ans..64CCard scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.Spezifische Transaktions-ID des Kartenschemas, die für nachfolgende Zahlungen mit gespeicherten Zugangsdaten, verzögerte Autorisierungen und Wiedereinreichungen erforderlich ist-on-file payments, delayed authorizations and resubmssions.
Statusa..20M

Staus of the transaction.

Values accepted:

  • Authorized
  • OK (Sale)
  • FAILED

In case of Authentication-only the Status will be either OK or FAILED.

Status der Transaction.

Zulässige Werte:

  • Authorized
  • OK (Sale)
  • FAILED

Im Fall von nur-Authentisierung ist der Status entweder OK oder the Status will be either OK or FAILED.

Table Excerpt Include
statictrue
nameDescription
pageDescription
typepage

Table Excerpt Include
statictrue
nameCode
pageCode
typepage

KeyFormatCNDDescriptionBeschreibung
cardJSONMCard response dataObjekt der Kartendaten
ipInfoJSONCObject containing IP information. Presence depends on the configuration for the merchant.Objekt mit IP-Informationen. Das Vorhandensein hängt von der Konfiguration des Händlers ab.
threeDSDataJSONMAuthentication dataObjekt der Authentisierungsdaten
resultsResponseJSONCIn case the authentication process included a cardholder challenge additional information about the challenge result will be providedFalls der Authentisierungsprozess eine Aufforderung für den Karteninhaber enthalten hat, werden zusätzliche Informationen über das Ergebnis der Aufforderung bereitgestellt

Table Excerpt Include
statictrue
nameUserData
pageUserData
typepage

Table Excerpt Include
statictrue
nameMAC
pageMAC
typepage




Extended Sequence Diagram

Multiexcerpt
MultiExcerptNameExtended Sequence Diagram
shouldDisplayInlineCommentsInIncludesfalse