You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

When requesting card payments via  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.

Notice 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


Payment Request

To retrieve a card form please submit the following data elements via HTTP POST request method to payssl.aspx.

Oops, it seems that you need to place a table or a macro generating a table within the Table Filter macro.

The table is being loaded. Please wait for a bit ...


KeyFormatCNDDescription
1

MerchantID

ans..30

M

Merchant identifier assigned by

2

MsgVer

ans..5

M

Message version.

Values accepted

  • 2.0
3

TransID

ans..64

M

Transaction identifier supplied by the merchant. Shall be unique for each payment
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 settlement file (CTSF) we cannot add the additional payment data.

5

Amount

n..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, 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.

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.

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

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 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 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.

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.

HTTP POST to URLSuccess / URLFailure / URLNotify

Oops, it seems that you need to place a table or a macro generating a table within the Table Filter macro.

The table is being loaded. Please wait for a bit ...

KeyFormatCNDDescription

MID

ans..30

M

MerchantID, assigned by

KeyFormatCNDDescription

MsgVer

ans..5

M

Message version.

Accepted values:

  • 2.0

KeyFormatCNDDescription
PayID

an32

M

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

KeyFormatCNDDescription
XID

an32

M

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

KeyFormatCNDDescription
TransID

ans..64

MTransactionID provided by you which should be unique for each payment

KeyFormatCNDDescription

schemeReferenceID

ans..64CCard scheme specific transaction ID required for subsequent credential-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.

KeyFormatCNDDescription
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!

KeyFormatCNDDescription
Code

n8

M

Error code according to  Response Codes (A4 Response codes)

KeyFormatCNDDescription
cardJSONMCard response data
ipInfoJSONCObject containing IP information. Presence depends on the configuration for the merchant.
threeDSDataJSONMAuthentication data
resultsResponseJSONCIn case the authentication process included a cardholder challenge additional information about the challenge result will be provided

KeyFormatCNDDescription
UserData

ans..1024

O

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

KeyFormatCNDDescription

MAC

an64

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


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.

Extended Sequence Diagram

  • No labels