Cards in plain text

1 Card data in plain text

This integration type is available only if you meet the PCI DSS requirements regarding storing and processing of card data. It also requires additional configuration. Therefore, before proceeding with the integration, please contact your sales representative in PayU.

You should annually complete a Self-Assessment Questionnaire (SAQ) and conduct on a quarterly basis network scan by an Approved Scan Vendor (ASV).

Additionally if you process over 6 million card transactions annually you should complete Report on Compliance (ROC) by Qualified Security Assessor (QSA).

You can find more information at Security Standards Council.

To facilitate recurring payments, the basic order create request, as described in creating a new order section must be enhanced with payMethods object and - if it is a payment with a stored card - either cardOnFile or recurring field.

The cardOnFile parameter should be used if payment is not recurring, but is either made with a stored card or the card is just being stored for future use:
  • FIRST - payment initialized by the card owner who agreed to save card for future use. In such situation strong authentication (3D Secure) is expected and CVV2 code should be provided,
  • STANDARD_CARDHOLDER - payment with stored card, initialized by the card owner. Depending of payment parameters (e.g. high transaction amount) strong authentication can be expected (3D Secure and/or CVV);
  • STANDARD_MERCHANT - payment with already saved card, initialized by the shop without the card owner participation. From the definition this payment type does not require strong authentication.
The recurring field marks the order as recurring payment (note: an order must be flagged as either "cardOnFile" or "recurring", sending both fields will return error).
  • FIRST - first transaction with full authentication (the user is present and has agreed to recurring payment terms),
  • STANDARD - subsequent recurring payment (user is not present).

Setting this parameter in the correct way can increase conversion for payment cards and can guarantee transaction security.

In case of one-time card payment, cardOnFile parameter should be skipped.

Sample payMethods.payMethod section supplemented with plain card data

                
                    "payMethods": {
                        "payMethod": {
                            "card": {
                                "number":"5100052384536818",
                                "expirationMonth":"11",
                                "expirationYear":"2020",
                                "cvv":"123"
                            }
                        }
                    },
                
                

In case you do not provide 3D Secure authentication result (see External 3D Secure parameters) section below), you should be prepared for handling responses with: WARNING_CONTINUE_3DS or WARNING_CONTINUE_CVV.

2 External 3D Secure parameters

In case of already existing integration with provider of 3D Secure service (later called 3DS) you can pass parameters that have been returned from 3DS handling process in OrderCreateRequest. Standard OrderCreateRequest should be extended by payMethods.threeDsData section containing result data from 3DS process.

WARNING_CONTINUE_3DS will never be returned if the result of 3DS handling process will be delivered with Order.

Sample threeDsData section for successful 3DS authentication

                    
                    "payMethods": {
                        "payMethod": {
                            ...
                            },
                            "threeDsData": {
                                "status3Ds": "AY",
                                "status3DsDescription": "3ds successfull",
                                "xid": "PL345346456",
                                "eciCode": "5",
                                "cavv": "AAABBBEAUAAAABgICABQAAAAAAA="
                            }
                        }
                    }
                

Sample threeDsData section for successful 3DS2.x authentication

                
                "payMethods": {
                    "payMethod": {
                        ...
                        },
                        "threeDsData": {
                            "status3Ds": "Y",
                            "status3DsDescription": "3ds2.x successfull",
                            "dsTransactionId": "3b31b19d-1c06-4ea4-a85a-00af10c66588",
                            "eciCode": "5",
                            "cavv": "AAABBBEAUAAAABgICABQAAAAAAA="
                        }
                    }
                }
                
            

Sample threeDsData section for card which issuer does not support 3DS

                    
                    "payMethods": {
                        "payMethod": {
                            ...
                            },
                            "threeDsData": {
                                "status3Ds": "VN",
                                "status3DsDescription": "Card is not participating in 3DS",
                                "xid": "PL345346456"
                            }
                        }
                    }
                    
                

Sample threeDsData section for 3DS authentication attempt

                    
                    "payMethods": {
                        "payMethod": {
                            ...
                            },
                            "threeDsData": {
                                "status3Ds": "AA",
                                "status3DsDescription": "3DS authentication attempt",
                                "xid": "PL345346456",
                                "eciCode": "6",
                                "cavv": "BwABCJQnYgAAACdENCdiAAAAAAA="
                            }
                        }
                    }
                    
                

Parameters used in the threeDsData section

Parameter Description
status3Ds 3DS status. This field informs with what status and in which moment 3DS process has ended.

If the 3DS process has ended at card 3DS verification stage then MPI response (final statuses - N or U) should be preceded by the letter "V".

If the 3DS process was completed at the stage of authentication of the 3DS (PARes) result received from the card issuer, then the original MPI response (final statuses - Y, N, A or U) should be preceded by the letter "A".

Hence the allowed values of this field:
  • VN – card does not support 3DS,
  • VU – payment organization / card issuer was not able to confirm if card support 3DS,
  • AY – successful 3DS authentication,
  • AU – it is not possible to authenticate 3DS result received from the card issuer,
  • AA – authentication attempt of 3DS result provided by card issuer.
Following values are allowed to be used while using 3DS2.x version of the service:
  • Y - successful 3DS2.x authentication,
  • A - 3DS2.x authentication attempt.
status3DsDescription Description related to 3DS result.

Optional field. However passing additional description with the MPI will allow better potential customer support from BOK.
xid XID - unique identifier of 3DS transaction given by the shop.

Field required within 3DS version 1 section. This field should not be sent when attempting 3DS2.x authentication.
dsTransactionId Field required within 3DS2.x section. This field should not be sent when attempting 3DS version 1 authentication.
eciCode E-commerce Indicator / UCAF.

Permitted values:
  • 5
  • 6
  • 7
  • 2
  • 1
  • 0
Optional field. It should be passed always if the MPI provided this information.
cavv 3DS cryptogram.

Optional field.It should be passed always if the MPI provided this information.