3D Secure 2.0 Payments – Nuvei Documentation

3D Secure 2.0 is the new authentication protocol that provides an additional layer of verification for card transactions. Strong Customer Authentication (SCA) requires merchants to integrate into the checkout flow a two-factor authentication, requiring their customers to use two out of three elements: something only the user knows like a password, something only the user possesses like the phone and something only the user possesses like a fingerprint.

Checkout the below example of a payment using the 3D Secure 2.0 protocol.

Although 3D Secure 2.0 protocol requires sending much more additional details, it increases the chances for a smooth and frictionless payment flow.

Request:

POST https://securetest.smart2pay.com/v1/payments
Authorization: Basic MTAxMDpnYWJp

{
  "Payment": {
  "MerchantTransactionID": "s2ptest_6a",
  "Amount": "100",
  "Currency": "EUR",
  "ReturnURL": "http://demo.smart2pay.com/redirect.php",
  "Description": "Test Description",
  "StatementDescriptor1": "Dynamic Test Description",
  "BillingAddress": {
    "City": "Iasi",
    "ZipCode": "7000-49",
    "State": "Iasi",
    "Street": "Sf Lazar",
    "StreetNumber": "37",
    "HouseNumber": "5A",
    "HouseExtension": "-",
    "Country": "RO"
    },
  "ShippingAddress": {
    "City": "Iasi",
    "ZipCode": "700049",
    "State": "Iasi",
    "Street": "Sf Lazar",
    "StreetNumber": "37",
    "HouseNumber": "-",
    "HouseExtension": "-",
    "Country": "RO" 
    },
  "Customer": {
    "MerchantCustomerID": "3452342354232",
    "Email": "accept@accept.com",
    "Firstname": "Test",
    "Lastname": "Person",   
    "SocialSecurityNumber": "45908-28324",
    "Phone": "0744-783322",
    "Company": "S2P",
    "Gender": "1"
    },
  "Card": {
    "HolderName": "Test Person",
    "Number": "4548812049400004",
    "ExpirationMonth": "11",
    "ExpirationYear": "2025",
    "SecurityCode": "123",
    "RequireSecurityCode": true
    },
  "Capture": false,
  "GenerateCreditCardToken": false,
  "PaymentTokenLifetime": 10,
  "3DSecure": true,
  "DeviceInfo": {
    "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
    "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
    "BrowserJavaEnabled": false,
    "BrowserJavaScriptEnabled": true,
    "BrowserLanguage": "ro-RO",
    "BrowserColorDepth": "24",
    "BrowserScreenHeight": "1080",
    "BrowserScreenWidth": "1920",
    "BrowserTimeZone": "-180"
    },
  "ScaExemption": "LowValueTransaction",
  "Language": "ro-RO",
  "SkinID": 200
  }
}

{"Payment":{"hint":"Payment structure","regexp":"","type":"object","MerchantTransactionID":{"hint":"Merchant Transaction ID, a number that uniquely identifies a transaction in your system.","regexp":"^[0-9a-zA-Z_-]{1,50}$","type":"string"},"SkinID":{"hint":"Skin ID to be used","regexp":"^\\d{1,12}$","type":"int"},"OriginatorTransactionID":{"hint":"Originator transaction ID, a number that uniquely identifies the transaction in the original requester\u2019s system.","regexp":"^[0-9a-zA-Z_-]{1,50}$","type":"string"},"Amount":{"hint":"The service(s)\/product(s) price on your website or application. The last two digits represent the decimal part (11.54 will be sent 1154). Please be aware that data type string is also accepted as long as it contains only digits","regexp":"^\\d{1,12}$","type":"int"},"Currency":{"hint":"The currency in which you sell the services or products. Format is according to ISO 4217, a three-letter code.","regexp":"^[a-zA-Z]{3}$","type":"string"},"ReturnURL":{"hint":"An URL at your end where the customer will be redirected after the payment process ends.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"Description":{"hint":"Text describing the service or product sold; will be displayed on the payment page.","regexp":"^(.{1,500})?$","type":"string"},"StatementDescriptor":{"hint":"Description per transaction that appears on the customer\u2019s billing statement, explaining a charge of the merchant. It helps the customer identify the purchase.","regexp":"^(.{1,250})?$","type":"string"},"BillingAddress":{"hint":"Billing Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Customer\u2018s country. Recommended to be sent in order to increase the conversion. If MethodID is missing, this field (taken from BillingAddress object) controls which payment methods are shown on the hosted payment pages. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}},"ShippingAddress":{"hint":"Shipping Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address (where you want your items delivered) in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Shipping country, where your customer\u2018s items should be delivered. It can be the same as the customer\u2018s billing address, or it can be different. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}},"Customer":{"hint":"Customer details","regexp":"","type":"object","ID":{"hint":"Customer ID, a unique number that identifies the customer in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"MerchantCustomerID":{"hint":"The ID of the customer in your system.","regexp":"^([0-9a-zA-Z_-]{1,50})?$","type":"string"},"Email":{"hint":"Customer\u2019s email","regexp":"^[a-zA-Z0-9\\._%+-]{1,100}@[a-zA-Z0-9\\.-]{1,40}\\.[a-zA-Z]{1,8}$","type":"string"},"FirstName":{"hint":"Customer\u2019s first name","regexp":"","type":"string"},"LastName":{"hint":"Customer\u2019s last name","regexp":"","type":"string"},"Gender":{"hint":"Customer\u2019s gender. It can have the following values: 1 - Male, 2 - Female.","regexp":"","type":"string"},"DateOfBirth":{"hint":"Customer date of birth","regexp":"^(((19|20)\\d\\d)(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))$","type":"date"},"SocialSecurityNumber":{"hint":"Customer\u2018s social or fiscal identifier","regexp":"","type":"string"},"Phone":{"hint":"Customer\u2019s phone including prefix","regexp":"","type":"string"},"Company":{"hint":"Company name (for legal entities)","regexp":"","type":"string"},"InputDateTime":{"hint":"Customer creation date","regexp":"","type":"datetime"}},"Card":{"hint":"Card details","regexp":"","type":"object","HolderName":{"hint":"The person whose name is on the credit card.","regexp":"^[^\\d]*$","type":"string"},"Number":{"hint":"The number of the credit card","regexp":"^(\\d{16,19})$","type":"string"},"ExpirationMonth":{"hint":"The expiration month of the credit card","regexp":"^(0?[1-9]|1[0-2])$","type":"string"},"ExpirationYear":{"hint":"The expiration year of the credit card","regexp":"^(20|)([0-9]{2})$","type":"string"},"IssuingBankCountry":{"hint":"Card issuing bank country","regexp":"^[a-zA-Z]{2}$","type":"string"},"SecurityCode":{"hint":"The card security code (also called CVV2) consists of a 3 or 4 digit number that appears on the credit card.","regexp":"^([0-9]){3,4}$","type":"string"},"RequireSecurityCode":{"hint":"If set to false when the security code parameter is not used, it will not redirect to the form page to fill in the security code, but the payment will be directly sent to the payment provider.","regexp":"","type":"bool"},"Token":{"hint":"Card token","regexp":"","type":"string"},"MaskedNumber":{"hint":"The card number masked. The last four digits remain unmasked.","regexp":"","type":"string"}},"CreditCardToken":{"hint":"Credit card token structure","regexp":"","type":"object","Value":{"hint":"Token value","regexp":"","type":"string"},"RequireSecurityCode":{"hint":"If set to false when the security code parameter is not used, it will not redirect to the form page to fill in the security code, but the payment will be directly sent to the payment provider.","regexp":"","type":"bool"},"SecurityCode":{"hint":"Token security code","regexp":"","type":"string"}},"Installments":{"hint":"Payment split into installments.\r\nAvailable installments number per country code:\r\nAR: 3, 6, 9, 12;\r\nBR: 2, 3, 4, 5, 6, 10, 12, 15, 18, 24;\r\nCL: 3, 6, 9, 12;\r\nCO: 3, 6, 9, 12, 24, 36;\r\nMX: 3, 6, 9, 12, 18;\r\nPE: 3, 6, 9, 12;\r\nTR: 3, 6, 9, 12.","regexp":"^\\d{1,12}$","type":"int"},"Splits":{"hint":"","regexp":"","type":"array of objects","SiteID":{"hint":"The ID of the site","regexp":"^\\d{1,12}$","type":"int"},"Amount":{"hint":"Split payment amount","regexp":"^\\d{1,12}$","type":"int"},"MerchantTransactionID":{"hint":"Payment merchant assigned transaction ID","regexp":"","type":"string"},"OriginatorTransactionID":{"hint":"Originator transaction ID, a number that uniquely identifies the transaction in the original requester\u2019s system.","regexp":"^[0-9a-zA-Z_-]{1,50}$","type":"string"}},"Capture":{"hint":"If set to true, the payment will be automatically captured.","regexp":"","type":"bool"},"Retry":{"hint":"If set to true, instructs Smart2Pay to retry sending the transaction to the same acquirer (for certain temporary technical errors) or to other acquirers (in case of business errors) according to your account settings.","regexp":"","type":"bool"},"3DSecure":{"hint":"To be set to true.","regexp":"","type":"bool"},"3DSecureData":{"hint":"Should contain authentication result obtained from your 3DS MPI Provider.","regexp":"","type":"object","AuthenticationStatus":{"hint":"The authentication status value. Possible values: \\\"Y\\\" = successful,\\\"N\\\" = failed.","regexp":"","type":"string"},"ECI":{"hint":"Electronic Commerce Indicator (ECI) is a value that is returned from the Directory Server (Visa, MasterCard and JCB) to indicate the authentication results of your customer\u2018s credit card payment on 3D Secure. ECI Values for Visa: 05, 06, 07; for Mastercard: 00, 01, 02; for JCB: 05, 06, 07.","regexp":"","type":"string"},"CAVV":{"hint":"The Cardholder Authentication Verification Value (CAVV) is a unique value generated by the issuer (or by Visa on the issuer\u2019s behalf) and is passed on to the acquirer to prove that the transaction has been authenticated. The use of CAVV helps secure the integrity of Verified by Visa (VbV) transactions by enabling end-to-end transaction traceability.","regexp":"","type":"string"},"DSID":{"hint":"The Directory Server unique ID assigned for this payment. This can be used for both 3DSecure v2.0 and 3DSecure v1.0. In 3DSecure v1.0 the parameter is known as XID.","regexp":"","type":"string"},"3DSecureVersion":{"hint":"The protocol version of 3D Secure.","regexp":"","type":"string"}},"DeviceInfo":{"hint":"Provides information regarding the customer\u2018s browser.","regexp":"","type":"object","BrowserAcceptHeader":{"hint":"The accept header value of the customer\u2018s browser. This field is required only if the cardholder\u2018s user agent supplied a value.","regexp":"","type":"string"},"BrowserUserAgent":{"hint":"The user agent value of the customer\u2018s browser.","regexp":"","type":"string"},"BrowserJavaEnabled":{"hint":"Boolean value indicating if the customer\u2018s browser is able to execute Java.","regexp":"","type":"bool"},"BrowserJavaScriptEnabled":{"hint":"Boolean value indicating if the customer\u2018s browser is able to execute JavaScript.","regexp":"","type":"bool"},"BrowserLanguage":{"hint":"The customer\u2018s browser language as defined in IETF BCP 47.","regexp":"","type":"string"},"BrowserColorDepth":{"hint":"Contains a value representing the bit depth of the colour palette, in bits per pixel, for displaying images.","regexp":"","type":"int"},"BrowserScreenHeight":{"hint":"Total height of the customer\u2018s screen in pixels.","regexp":"","type":"int"},"BrowserScreenWidth":{"hint":"Total width of the customer\u2018s screen in pixels.","regexp":"","type":"int"},"BrowserTimeZone":{"hint":"Difference between UTC time and the customer\u2018s browser local time in minutes.","regexp":"","type":"int"}},"ScaExemption":{"hint":"Merchant can explicitly apply for an exemption from SCA sending this parameter. Possible values: LowValueTransaction, TransactionRiskAnalysis, MerchantInitiatedTransaction, TrustedBeneficiary, CorporatePayments.","regexp":"","type":"string"},"CardOnFile":{"hint":"CardOnFile transaction details","regexp":"","type":"object","IsInitial":{"hint":"Must be sent \u201ctrue\u201c when the payment is the first in a subsequent payments chain. Must be sent \u201cfalse\u201c when the payment is not the first in a subsequent payments chain.","regexp":"","type":"bool"},"TransactionType":{"hint":"CardOnFile transactions type. Possible values: Installments, Recurring, Reauthorization, Resubmission, Delayed, Incremental, No Show, Others.","regexp":"","type":"string"},"InitialPaymentID":{"hint":"Initial PaymentID of the payment that generated the CardOnFile. This field must be sent when IsInitial field has the value \u201cfalse\u201c. If the field IsInitial has the value \u201ctrue\u201c, the InitialPaymentID should not be sent, but it will be received in the response.","regexp":"","type":"int"}},"Language":{"hint":"Language used","regexp":"","type":"string"},"GenerateCreditCardToken":{"hint":"If set to true, a token element is sent containing the value of the newly created token in the response\/notification.","regexp":"","type":"bool"},"Moto":{"hint":"If set to true, the payment will be marked at the acquirer as Mail Order Telephone Order type of transaction. This is not available for all acquirers.","regexp":"","type":"bool"},"PaymentTokenLifetime":{"hint":"The time in minutes after the token used for redirectURL expires. It defaults to 5 minutes if not sent.","regexp":"^\\d{1,12}$","type":"int"}}}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 208161,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190828091954",
        "MerchantTransactionID": "s2ptest_6a",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Test Description",
        "StatementDescriptor": "Static Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": {
            "ID": 647,
            "MerchantCustomerID": "3452342354232",
            "Email": "accept@accept.com",
            "FirstName": "Test",
            "LastName": "Person",
            "Gender": "1",
            "SocialSecurityNumber": "45908-28324",
            "Phone": "0744-783322",
            "Company": "S2P"
        },
        "BillingAddress": {
            "ID": 253,
            "City": "Iasi",
            "ZipCode": "7000-49",
            "State": "Iasi",
            "Street": "Sf Lazar",
            "StreetNumber": "37",
            "HouseNumber": "5A",
            "HouseExtension": "-",
            "Country": "RO"
        },
        "ShippingAddress": {
            "ID": 87,
            "City": "Iasi",
            "ZipCode": "700049",
            "State": "Iasi",
            "Street": "Sf Lazar",
            "StreetNumber": "37",
            "HouseNumber": "-",
            "HouseExtension": "-",
            "Country": "RO"
        },
        "Articles": null,
        "Card": {
            "HolderName": "Test Person",
            "Number": "VISA-0004",
            "ExpirationMonth": "11",
            "ExpirationYear": "2025",
            "IssuingBankCountry": null
        },
        "CreditCardToken": null,
        "Status": {
            "ID": 9,
            "Info": "Authorized",
            "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "591659",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "RedirectURL": null,
        "3DSecure": true,
        "DeviceInfo": {
            "BrowserAcceptHeader": "application/json, text/javascript, */*; q=0.01",
            "BrowserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
            "BrowserJavaEnabled": false,
            "BrowserJavaScriptEnabled": true,
            "BrowserLanguage": "ro-RO",
            "BrowserColorDepth": "24",
            "BrowserScreenHeight": "1080",
            "BrowserScreenWidth": "19200",
            "BrowserTimeZone": "-180"
        },
        "ScaExemption": null,
        "Fraud": {
            "Status": "Accept",
            "Score": 31,
            "Reason": "No decision provided"
        }
    }
}

{"Payment":{"hint":"Payment structure","regexp":"","type":"object","ID":{"hint":"GlobalPay transaction ID, a unique number that identifies the transaction in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"SkinID":{"hint":"Skin ID to be used","regexp":"^\\d{1,12}$","type":"int"},"ClientIP":{"hint":"The IP address of the customer","regexp":"^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$","type":"string"},"Created":{"hint":"Date and time when the transaction was created in GlobalPay system.","regexp":"","type":"datetime"},"MerchantTransactionID":{"hint":"Merchant Transaction ID, a number that uniquely identifies a transaction in your system.","regexp":"^[0-9a-zA-Z_-]{1,50}$","type":"string"},"OriginatorTransactionID":{"hint":"Originator transaction ID, a number that uniquely identifies the transaction in the original requester\u2019s system.","regexp":"^[0-9a-zA-Z_-]{1,50}$","type":"string"},"Amount":{"hint":"The service(s)\/product(s) price on your website or application. The last two digits represent the decimal part (11.54 will be sent 1154). Please be aware that data type string is also accepted as long as it contains only digits","regexp":"^\\d{1,12}$","type":"int"},"Currency":{"hint":"The currency in which you sell the services or products. Format is according to ISO 4217, a three-letter code.","regexp":"^[A-Z]{3}$","type":"string"},"CapturedAmount":{"hint":"The payment\u2018s captured amount. The last two digits represent the decimal part (11.54 will be sent 1154). Please be aware that data type string is also accepted as long as it contains only digits.","regexp":"^\\d{1,12}$","type":"int"},"ReturnURL":{"hint":"An URL at your end where the customer will be redirected after the payment process ends.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"Description":{"hint":"Text describing the service or product sold; will be displayed on the payment page.","regexp":"^.{1,255}$","type":"string"},"MethodID":{"hint":"The ID of the payment method.","regexp":"^\\d{1,12}$","type":"int"},"MethodOptionID":{"hint":"The ID of the payment option; can be used when the payment method has multiple payment options (e.g. ING bank is an option for iDEAL).","regexp":"^([0-9]{1,10})$","type":"int"},"IncludeMethodIDs":{"hint":"Methods can be included in this list and will be shown to the customer on the payment page. Subset of Smart2Pay payment methods from the ones assigned to you.","regexp":"","type":"array"},"ExcludeMethodIDs":{"hint":"Excluded methods will be shown to the customer in this list on the payment page. Subset of Smart2Pay payment methods from the ones assigned to you.","regexp":"","type":"array"},"PrioritizeMethodIDs":{"hint":"A sorted list of methods assigned to you. This is the order in which the methods will be displayed in the payment page.","regexp":"","type":"array"},"SiteID":{"hint":"The ID of the site","regexp":"^([0-9]{1,10})$","type":"int"},"NotificationDateTime":{"hint":"Date and time of payment notification","regexp":"","type":"datetime"},"Customer":{"hint":"Customer details","regexp":"","type":"object","ID":{"hint":"Customer ID, a unique number that identifies the customer in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"MerchantCustomerID":{"hint":"The ID of the customer in your system.","regexp":"^([0-9a-zA-Z_-]{1,50})?$","type":"string"},"Email":{"hint":"Customer\u2019s email","regexp":"^[a-zA-Z0-9\\._%+-]{1,100}@[a-zA-Z0-9\\.-]{1,40}\\.[a-zA-Z]{1,8}$","type":"string"},"FirstName":{"hint":"Customer\u2019s first name","regexp":"","type":"string"},"LastName":{"hint":"Customer\u2019s last name","regexp":"","type":"string"},"Gender":{"hint":"Customer\u2019s gender. It can have the following values: 1 - Male, 2 - Female.","regexp":"","type":"string"},"DateOfBirth":{"hint":"Customer date of birth","regexp":"^(((19|20)\\d\\d)(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))$","type":"date"},"SocialSecurityNumber":{"hint":"Customer\u2018s social or fiscal identifier","regexp":"","type":"string"},"Phone":{"hint":"Customer\u2019s phone including prefix","regexp":"","type":"string"},"Company":{"hint":"Company name (for legal entities)","regexp":"","type":"string"},"InputDateTime":{"hint":"Customer creation date","regexp":"","type":"datetime"}},"BillingAddress":{"hint":"Billing Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Customer\u2018s country. Recommended to be sent in order to increase the conversion. If MethodID is missing, this field (taken from BillingAddress object) controls which payment methods are shown on the hosted payment pages. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}},"ShippingAddress":{"hint":"Shipping Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address (where you want your items delivered) in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Shipping country, where your customer\u2018s items should be delivered. It can be the same as the customer\u2018s billing address, or it can be different. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}},"Articles":{"hint":"The services\/products purchased from the website. Mandatory to be sent for Klarna Invoice and Klarna Payments payment methods.","regexp":"","type":"array of objects","MerchantArticleID":{"hint":"The ID of the article in your system","regexp":"^\\d{1,19}$","type":"string"},"Name":{"hint":"Article\u2019s name","regexp":"^.{1,250}$","type":"string"},"Quantity":{"hint":"The number of products. If is not sent the default value is 1.","regexp":"^\\d{1,3}$","type":"int"},"Price":{"hint":"The price for one item","regexp":"","type":"int"},"VAT":{"hint":"Value-Added Tax ( it is a tax in percent on the purchase price)","regexp":"^\\d{1,4}$","type":"int"},"Discount":{"hint":"The percent on the original price offered by you as discount. The last two digits represent the decimal part (10% will be sent 1000).","regexp":"^\\d{1,4}$","type":"int"},"DiscountValue":{"hint":"The fixed value on the original price offered by you as discount. The last two digits represent the decimal part (10 GBP will be sent 1000).","regexp":"^\\d{1,4}$","type":"int"},"Type":{"hint":"The type of article. It can have the following values: 4 - Discount, 5 -Physical, 6 - Shipping_fee, 7 - Sales_tax, 8 - Digital, 9 - Gift_card, 10 - Store_credit, 11 - Surcharge.","regexp":"^(1|2|3|4|5|6|7|8|9|10|11)$","type":"int"},"TaxType":{"hint":"The type of tax. It can have the following values: 1 - without VAT, 2 - VAT at the rate of 0%, 3 - VAT of the receipt at the rate of 10%, 4 - VAT of the receipt at the rate of 18%, 5 - VAT of the receipt at the applicable rate of 10\/110, 6 - VAT of the receipt at the applicable rate of 18\/118.","regexp":"^(1|2|3|4|5|6)$","type":"int"}},"Splits":{"hint":"","regexp":"","type":"array of objects","ID":{"hint":"Payment split ID","regexp":"^\\d{1,12}$","type":"int"},"PaymentID":{"hint":"Payment ID","regexp":"^\\d{1,12}$","type":"int"},"SiteID":{"hint":"The ID of the site","regexp":"^\\d{1,12}$","type":"int"},"MerchantTransactionID":{"hint":"Payment merchant assigned transaction ID","regexp":"","type":"string"},"OriginatorTransactionID":{"hint":"Originator transaction ID, a number that uniquely identifies the transaction in the original requester\u2019s system.","regexp":"^[0-9a-zA-Z_-]{1,50}$","type":"string"},"Created":{"hint":"Split payment creation time","regexp":"","type":"datetime"},"Amount":{"hint":"Split payment amount","regexp":"^\\d{1,12}$","type":"int"},"Currency":{"hint":"The currency in which you sell the services or products. Format is according to ISO 4217, a three-letter code.","regexp":"^[A-Z]{3}$","type":"string"},"CapturedAmount":{"hint":"Payment amount captured","regexp":"^\\d{1,12}$","type":"int"},"Status":{"hint":"","regexp":"","type":"object","ID":{"hint":"Status ID","regexp":"","type":"int"},"Info":{"hint":"The description of the status","regexp":"","type":"string"},"Reasons":{"hint":"The reasons why the payment got to this status.","regexp":"","type":"array of objects","Code":{"hint":"The id of the message type transmitted in the response. See our section GlobalPay Return Codes for a complete description.","regexp":"","type":"int"},"Info":{"hint":"The message body","regexp":"","type":"string"}}}},"Details":{"hint":"In some cases we send various details about the payment (e.g. Reference Number and Bank Details of the Customer for Bank Transfer payments).","regexp":"","type":"object","BankCode":{"hint":"Customer\u2019s Bank Code. Also known as BIC or Swift_BIC. Bank Identifier Code (BIC), a unique identification code for a particular bank (consists of 8-11 alphanumeric characters).","regexp":"","type":"string"},"AccountNumber":{"hint":"Account number","regexp":"","type":"string"},"IBAN":{"hint":"IBAN (International Bank Account Number) a code (up to 34 alphanumeric characters) that uniquely identifies an account held at any bank anywhere in the world.","regexp":"","type":"string"},"BIC":{"hint":"Bank Identifier Code (BIC), a unique identification code for a particular bank (consists of 8-11 alphanumeric characters).","regexp":"","type":"string"},"EntityID":{"hint":"Payment entity ID","regexp":"","type":"string"},"ReferenceID":{"hint":"Payment reference ID","regexp":"","type":"string"},"EntityNumber":{"hint":"Payment entity number","regexp":"","type":"string"},"ReferenceNumber":{"hint":"Payment reference number","regexp":"","type":"string"},"AccountHolder":{"hint":"The person whose name is on the bank account.","regexp":"","type":"string"},"BankName":{"hint":"The name of the Bank","regexp":"","type":"string"},"BankSortCode":{"hint":"Bank sort code identifies both the bank and the branch where the account is held (consists of 6 digits).","regexp":"","type":"string"},"SocialSecurityNumber":{"hint":"Payer social security number","regexp":"","type":"string"},"SWIFT_BIC":{"hint":"Swift Code, a standard format of Bank Identifier Codes (BIC), is a unique identification code for a particular bank (consists of 8-11 alphanumeric characters).","regexp":"","type":"string"},"AccountCurrency":{"hint":"The currency in which the account is kept. Format is according to ISO 4217, a three-letter code.","regexp":"","type":"string"},"PrepaidCard":{"hint":"Prepaid card number","regexp":"","type":"string"},"PrepaidCardPIN":{"hint":"Prepaid card PIN","regexp":"","type":"string"},"SerialNumbers":{"hint":"Serial numbers","regexp":"","type":"string"},"Wallet":{"hint":"Customer wallet","regexp":"","type":"string"},"PayerCountry":{"hint":"Payer country ISO 2 characters","regexp":"^[a-zA-Z]{2}$","type":"string"},"PayerEmail":{"hint":"Payer email address","regexp":"^[a-zA-Z0-9\\._%+-]{1,100}@[a-zA-Z0-9\\.-]{1,40}\\.[a-zA-Z]{1,8}$","type":"string"},"PayerPhone":{"hint":"Payer phone number","regexp":"^.{1,20}$","type":"string"},"BillingCycleStart":{"hint":"The date and time when the payment billing cycle starts.","regexp":"","type":"date"},"BillingCycleEnd":{"hint":"The date and time when the payment billing cycle ends.","regexp":"","type":"date"},"UnsubscribeInstructions":{"hint":"Unsubscribe instructions","regexp":"","type":"string"},"CustomerLoginID":{"hint":"Customer login ID","regexp":"","type":"string"},"PaidAmount":{"hint":"Paid amount","regexp":"","type":"int"},"PaidCurrency":{"hint":"Paid currency","regexp":"^[a-zA-Z]{3}$","type":"string"},"ProviderExchangeRate":{"hint":"Provider exchange rate","regexp":"","type":"float"},"PayerBankAccountID":{"hint":"Payer bank account ID","regexp":"","type":"string"},"IsMobileApp":{"hint":"Payment is initiated in a mobile app","regexp":"","type":"bool"},"IsOffline":{"hint":"Offline payment method","regexp":"","type":"bool"},"StoreName":{"hint":"Store name. Can be null only when the store information is verified","regexp":"","type":"string"},"StoreId":{"hint":"Store ID","regexp":"","type":"string"},"TerminalID":{"hint":"Terminal ID","regexp":"","type":"string"}},"CaptureDetails":{"hint":"","regexp":"","type":"object","ID":{"hint":"Capture ID","regexp":"^\\d{1,12}$","type":"int"},"Amount":{"hint":"Capture amount","regexp":"^\\d{1,12}$","type":"int"},"Status":{"hint":"Preapproval ID","regexp":"","type":"object","ID":{"hint":"Status ID","regexp":"","type":"int"},"Info":{"hint":"The description of the status","regexp":"","type":"string"},"Reasons":{"hint":"The reasons why the payment got to this status.","regexp":"","type":"array of objects","Code":{"hint":"The id of the message type transmitted in the response. See our section GlobalPay Return Codes for a complete description.","regexp":"","type":"int"},"Info":{"hint":"The message body","regexp":"","type":"string"}}}},"ReferenceDetails":{"hint":"Reference details structure","regexp":"","type":"object","BankCode":{"hint":"Customer\u2019s Bank Code. Also known as BIC or Swift_BIC. Bank Identifier Code (BIC), a unique identification code for a particular bank (consists of 8-11 alphanumeric characters).","regexp":"","type":"string"},"BankName":{"hint":"The name of the Bank","regexp":"","type":"string"},"EntityID":{"hint":"Entity ID","regexp":"","type":"string"},"EntityNumber":{"hint":"Entity number","regexp":"","type":"string"},"ReferenceID":{"hint":"Reference ID","regexp":"","type":"string"},"ReferenceNumber":{"hint":"Reference number","regexp":"","type":"string"},"SwiftBIC":{"hint":"Swift Code, a standard format of Bank Identifier Codes (BIC), is a unique identification code for a particular bank (consists of 8-11 alphanumeric characters).","regexp":"","type":"string"},"AccountCurrency":{"hint":"The currency in which the account is kept. Format is according to ISO 4217, a three-letter code.","regexp":"","type":"string"},"AccountNumber":{"hint":"Account number","regexp":"","type":"string"},"AccountHolder":{"hint":"The person whose name is on the bank account.","regexp":"","type":"string"},"IBAN":{"hint":"IBAN (International Bank Account Number) a code (up to 34 alphanumeric characters) that uniquely identifies an account held at any bank anywhere in the world.","regexp":"","type":"string"},"AmountToPay":{"hint":"Amount to be paid","regexp":"","type":"string"},"QRCodeURL":{"hint":"QRCode URL","regexp":"","type":"string"},"BoletoURL":{"hint":"Boleto URL","regexp":"","type":"string"},"Instructions":{"hint":"Payment Instructions","regexp":"","type":"string"}},"CustomParameters":{"hint":"We can collect additional information on the payment flow if you instruct our Support Team to configure this feature for you. The data we gather will be notified in this object.","regexp":"","type":"array"},"PreapprovalID":{"hint":"GlobalPay Preapproval ID, a number that uniquely identifies the preapproval in GlobalPay system. You receive it via a notification and it is used to initiate recurring payments.\r\nFor Cards (69) and Klarna Invoice (75), simply send in this field the initial GlobalPay PaymentID received in the notification of the initial successful one-off payment that the customer has made.","regexp":"^\\d{1,12}$","type":"int"},"Status":{"hint":"Payment status","regexp":"","type":"object","ID":{"hint":"The ID of the payment status. It can have the following values: 1 - Open, 2 - Success, 3 - Cancelled, 4 - Failed, 5 - Expired, 9 - Authorized.","regexp":"","type":"int"},"Info":{"hint":"The description of the status","regexp":"","type":"string"},"Reasons":{"hint":"The reasons why the payment got to this status.","regexp":"","type":"array of objects","Code":{"hint":"The id of the message type transmitted in the response. See our section GlobalPay Return Codes for a complete description.","regexp":"","type":"int"},"Info":{"hint":"The message body","regexp":"","type":"string"}}},"MethodTransactionID":{"hint":"The Acquirer Reference Number (ARN), a unique number that tags a credit card transaction\/refund when it goes from the merchant bank (the acquiring bank) through the card scheme to the cardholder\\'s bank (the issuer). This number can be used by issuing banks to trace a transaction with an acquirer.","regexp":"","type":"string"},"AuthorizationCode":{"hint":"Acquirer Authorization Code","regexp":"","type":"int"},"Capture":{"hint":"If set to true, the payment will be automatically captured.","regexp":"","type":"bool"},"TokenLifetime":{"hint":"The time in minutes after the token used for redirectURL expires. It defaults to 5 minutes if not sent.","regexp":"^\\d{1,12}$","type":"int"},"PaymentTokenLifetime":{"hint":"The time in minutes after the token used for redirectURL expires. It defaults to 5 minutes if not sent.","regexp":"^\\d{1,12}$","type":"int"},"RedirectInIframe":{"hint":"If set true, the payment page will be shown in an Iframe.","regexp":"","type":"bool"},"RedirectMerchantInIframe":{"hint":"Payment redirect in IFrame","regexp":"","type":"bool"},"RedirectURL":{"hint":"GlobalPay redirect URL, an URL where you need to redirect the customer after you receive the response from the API.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"PreapprovalDetails":{"hint":"Preapproval details","regexp":"","type":"object","PreapprovedMaximumAmount":{"hint":"Preapproval maximum amount. Please be aware that data type string is also accepted as long as it contains only digits.","regexp":"^\\d{1,12}$","type":"int"},"MerchantPreapprovalID":{"hint":"Preapproval id provided by merchant","regexp":"","type":"string"},"Frequency":{"hint":"Preapproval frequency \u2013 how often can the customer be billed. It can be onetime\/daily\/weekly\/monthly depending on the country and the mobile carrier.","regexp":"","type":"string"},"PreapprovalDescription":{"hint":"Preapproval description","regexp":"","type":"string"}},"InvalidRequestID":{"hint":"If the validation fails and a payment cannot be inserted then an invalid request is inserted in the database and the ID of the newly inserted invalid request is sent to the merchant in the Payment response (in element InvalidRequestID, its value prefixed with \u201di\u201d - to not be confused with the Payment ID).","regexp":"","type":"string"},"StatementDescriptor":{"hint":"Description per transaction that appears on the customer\u2019s billing statement, explaining a charge of the merchant. It helps the customer identify the purchase.","regexp":"","type":"string"},"CreditCardToken":{"hint":"Credit card token structure","regexp":"","type":"object","Value":{"hint":"Token value","regexp":"","type":"string"},"RequireSecurityCode":{"hint":"If set to false when the security code parameter is not used, it will not redirect to the form page to fill in the security code, but the payment will be directly sent to the payment provider.","regexp":"","type":"bool"},"SecurityCode":{"hint":"Token security code","regexp":"","type":"string"}},"Installments":{"hint":"Payment split into installments.\r\nAvailable installments number per country code:\r\nAR: 3, 6, 9, 12;\r\nBR: 2, 3, 4, 5, 6, 10, 12, 15, 18, 24;\r\nCL: 3, 6, 9, 12;\r\nCO: 3, 6, 9, 12, 24, 36;\r\nMX: 3, 6, 9, 12, 18;\r\nPE: 3, 6, 9, 12;\r\nTR: 3, 6, 9, 12.","regexp":"^\\d{1,12}$","type":"int"},"Retry":{"hint":"If set to true, instructs Smart2Pay to retry sending the transaction to the same acquirer (for certain temporary technical errors) or to other acquirers (in case of business errors) according to your account settings.","regexp":"","type":"bool"},"3DSecure":{"hint":"To be set to true for Payments using 3DSecure authentication.","regexp":"","type":"bool"},"3DSecureData":{"hint":"Should contain authentication result obtained from your 3DS MPI Provider.","regexp":"","type":"object","AuthenticationStatus":{"hint":"The authentication status value. Possible values: \\\"Y\\\" = successful,\\\"N\\\" = failed.","regexp":"","type":"string"},"ECI":{"hint":"Electronic Commerce Indicator (ECI) is a value that is returned from the Directory Server (Visa, MasterCard and JCB) to indicate the authentication results of your customer\u2018s credit card payment on 3D Secure. ECI Values for Visa: 05, 06, 07; for Mastercard: 00, 01, 02; for JCB: 05, 06, 07.","regexp":"","type":"string"},"CAVV":{"hint":"The Cardholder Authentication Verification Value (CAVV) is a unique value generated by the issuer (or by Visa on the issuer\u2019s behalf) and is passed on to the acquirer to prove that the transaction has been authenticated. The use of CAVV helps secure the integrity of Verified by Visa (VbV) transactions by enabling end-to-end transaction traceability.","regexp":"","type":"string"},"DSID":{"hint":"The Directory Server unique ID assigned for this payment. This can be used for both 3DSecure v2.0 and 3DSecure v1.0. In 3DSecure v1.0 the parameter is known as XID.","regexp":"","type":"string"},"3DSecureVersion":{"hint":"The protocol version of 3D Secure.","regexp":"","type":"string"}},"DeviceInfo":{"hint":"Provides information regarding the customer\u2018s browser.","regexp":"","type":"object","BrowserAcceptHeader":{"hint":"The accept header value of the customer\u2018s browser. This field is required only if the cardholder\u2018s user agent supplied a value.","regexp":"","type":"string"},"BrowserUserAgent":{"hint":"The user agent value of the customer\u2018s browser.","regexp":"","type":"string"},"BrowserJavaEnabled":{"hint":"Boolean value indicating if the customer\u2018s browser is able to execute Java.","regexp":"","type":"bool"},"BrowserJavaScriptEnabled":{"hint":"Boolean value indicating if the customer\u2018s browser is able to execute JavaScript.","regexp":"","type":"bool"},"BrowserLanguage":{"hint":"The customer\u2018s browser language as defined in IETF BCP 47.","regexp":"","type":"string"},"BrowserColorDepth":{"hint":"Contains a value representing the bit depth of the colour palette, in bits per pixel, for displaying images.","regexp":"","type":"int"},"BrowserScreenHeight":{"hint":"Total height of the customer\u2018s screen in pixels.","regexp":"","type":"int"},"BrowserScreenWidth":{"hint":"Total width of the customer\u2018s screen in pixels.","regexp":"","type":"int"},"BrowserTimeZone":{"hint":"Difference between UTC time and the customer\u2018s browser local time in minutes.","regexp":"","type":"int"}},"ScaExemption":{"hint":"Merchant can explicitly apply for an exemption from SCA sending this parameter. Possible values: LowValueTransaction, TransactionRiskAnalysis, MerchantInitiatedTransaction, TrustedBeneficiary, CorporatePayments.","regexp":"","type":"string"},"CardOnFile":{"hint":"CardOnFile transaction details","regexp":"","type":"object","IsInitial":{"hint":"Must be sent \u201ctrue\u201c when the payment is the first in a subsequent payments chain. Must be sent \u201cfalse\u201c when the payment is not the first in a subsequent payments chain.","regexp":"","type":"bool"},"TransactionType":{"hint":"CardOnFile transactions type. Possible values: Installments, Recurring, Reauthorization, Resubmission, Delayed, Incremental, No Show, Others.","regexp":"","type":"string"},"InitialPaymentID":{"hint":"Initial PaymentID of the payment that generated the CardOnFile. This field must be sent when IsInitial field has the value \u201cfalse\u201c. If the field IsInitial has the value \u201ctrue\u201c, the InitialPaymentID should not be sent, but it will be received in the response.","regexp":"","type":"int"}},"Card":{"hint":"Card details","regexp":"","type":"object","HolderName":{"hint":"The person whose name is on the credit card.","regexp":"^[^\\d]*$","type":"string"},"Number":{"hint":"The number of the credit card","regexp":"^(\\d{16,19})$","type":"string"},"ExpirationMonth":{"hint":"The expiration month of the credit card","regexp":"^(0?[1-9]|1[0-2])$","type":"string"},"ExpirationYear":{"hint":"The expiration year of the credit card","regexp":"^(20|)([0-9]{2})$","type":"string"},"IssuingBankCountry":{"hint":"Card issuing bank country","regexp":"^[a-zA-Z]{2}$","type":"string"},"SecurityCode":{"hint":"The card security code (also called CVV2) consists of a 3 or 4 digit number that appears on the credit card.","regexp":"^([0-9]){3,4}$","type":"string"},"RequireSecurityCode":{"hint":"If set to false when the security code parameter is not used, it will not redirect to the form page to fill in the security code, but the payment will be directly sent to the payment provider.","regexp":"","type":"bool"},"Token":{"hint":"Card token","regexp":"","type":"string"},"MaskedNumber":{"hint":"The card number masked. The last four digits remain unmasked.","regexp":"","type":"string"}},"Fraud":{"hint":"Fraud check structure","regexp":"","type":"object","Status":{"hint":"Fraud check status","regexp":"","type":"string"},"CheckMode":{"hint":"Fraud check mode","regexp":"","type":"string"},"Score":{"hint":"Fraud check score","regexp":"","type":"int"},"Reason":{"hint":"Fraud check reason","regexp":"","type":"string"}},"Moto":{"hint":"If set to true, the payment will be marked at the acquirer as Mail Order Telephone Order type of transaction. This is not available for all acquirers.","regexp":"","type":"bool"}}}

POST https://securetest.smart2pay.com/v1/payments Authorization: Basic MTAxMDpnYWJp { "Payment": { "MerchantTransactionID": "s2ptest_3a", "Amount": "100", "Currency": "EUR", "ReturnURL": "http://demo.smart2pay.com/redirect.php", "Description": "Test Description", "StatementDescriptor": "Dynamic Test Description", "Card": { "HolderName": "Test Person", "Number": "4548812049400004", "ExpirationMonth": "11", "ExpirationYear": "2025", "SecurityCode": "123", "RequireSecurityCode": true }, "Capture": false, "GenerateCreditCardToken": false, "PaymentTokenLifetime": 10, "3DSecure": true, "3DSecureData": { "AuthenticationStatus": "Y", "ECI": "05", "CAVV": "MDA5ODYyNjQxMzEyNzQxMTQ4NzA=", "DSID": "c272b04f-6e7b-43a2-bb78-90f4fb94aa25", "3DSecureVersion": "2.1.0" }, "ScaExemption": "LowValueTransaction", "Language": "ro-RO", "SkinID": 200 } }

HTTP/1.1 201 Created Content-Type: application/json; charset=utf-8 { "Payment": { "ID": 208158, "ClientIP": null, "SkinID": 200, "Created": "20190828082527", "MerchantTransactionID": "s2ptest_3a", "OriginatorTransactionID": null, "Amount": 100, "Currency": "EUR", "CapturedAmount": "0", "ReturnURL": "http://demo.smart2pay.com/redirect.php", "Description": "Test Description", "StatementDescriptor": "Dynamic Test Description", "MethodID": 6, "MethodOptionID": null, "SiteID": 1010, "NotificationDateTime": null, "Customer": null, "BillingAddress": null, "ShippingAddress": null, "Articles": null, "Card": { "HolderName": "Test Person", "Number": "VISA-0004", "ExpirationMonth": "11", "ExpirationYear": "2025", "IssuingBankCountry": null }, "CreditCardToken": null, "Status": { "ID": 9, "Info": "Authorized", "Reasons": [] }, "MethodTransactionID": null, "AuthorizationCode": "143383", "PaymentTokenLifetime": 10, "Capture": false, "RedirectURL": null, "3DSecure": true, "3DSecureData": { "AuthenticationStatus": "Y", "ECI": "05", "CAVV": "MDA5ODYyNjQxMzEyNzQxMTQ4NzA=", "DSID": "c272b04f-6e7b-43a2-bb78-90f4fb94aa25", "3DSecureVersion": "2.1.0" }, "DeviceInfo": null, "ScaExemption": "LowValueTransaction", "Fraud": { "Status": "Accept", "Score": 31, "Reason": "No decision provided" } } }