Testing Requirements

Test Amounts

Before going live you will first complete a number of test card transactions on our test environment. We have provided a range of amounts that you can use to check all the transactional statuses. Using the below amounts will produce specific responses in order for you to test different scenarios.

Please be aware that all the possible statuses of the transactions that are returned in responses are based on the values assigned in the Amount field. If you want to obtain a specific status, simply enter a specific amount as the transaction amount. Below you will find different amounts to simulate certain situations and statuses.

The amount’s last two digits represent the decimal part (11.54 will be sent 1154).

Test Amounts
Value Status Description
1 – 10000 Captured / Authorized For this amount range all the actions will be successful: payment authorization, capture action, cancel action, refund action.
10001 Failed All the transactions having this amount will fail.
10002 QueuedForCapturing

If you set capture flag to true it will return status QueuedForCapturing with return code: 5288: “Capture failed but will retry again later”.

If you set capture flag to false it will return status Authorized. Then if you sent a capture request it will receive status QueuedForCapturing with return code: 5288: “Capture failed but will retry again later”.

10003 CaptureRequested

If you set capture flag to true it will return status CaptureRequested.

If you set capture flag to false it will return status Authorized. Then if you sent a capture request it will receive status CaptureRequested.

10004 Transaction: Captured; Refund: Open If this amount will be used for a transaction it will be captured but the refund will remain Open.
10005 Failed Capture failed with timelimit reached. The timelimit for capture action is overdue.
10006 QueuedForCanceling If you set capture flag to false it will return status Authorized. Then if you sent a cancel request it will receive status QueuedForCanceling with return code: 5289: “Cancel failed but will retry again later”.
10201 – 10299 Transaction: Captured; Refund: Failed If any of the amounts in this range limit are used for a transaction it will be Captured but the refund will fail.
20001 – 30000 Failed If any of the amounts in this range limit are used for a transaction it will fail and it will receive status Failed with return code: 5291: “Security code (CVV2/CVC2) is incorrect”.
30001 – 30200 Captured / Authorized For this amount range all the actions will be successful: payment authorization, capture action, cancel action, refund action. For the initial request there is a delay in seconds according to the last 3 digits (from 1 – 200 seconds).

Test Credit Card Numbers

For testing purposes, please use the following credit card numbers:

Test Credit Card Numbers
Credit Card Name Credit Card Number
Visa: 4111111111111111
4024007189870784
4548812049400004
Mastercard: 5148196509775860
5443066050671259
Discover: 6011087785272940
6011235328768235
UnionPay: 6226388000000095
6216261000000000018
Visa Electron: 5443066050671259
4917300800000000
American Express: 345364891980314
372986503275489
Diners Club: 30120905411096
38341714925074
Hipercard: 6062825624254001
JCB: 3158178601355868
210076836080396
InstaPayment: 6385756289989351
6390524121376333

For testing purposes, please use only the credit card numbers from the above list! If any other credit card number is used for a test transaction it will fail and it will receive status Failed with return code: 5287: “Invalid card for test transaction”.

Server to Server Card Payment

If you initiate a payment with the GenerateCreditCardToken element set to false, the token element is not sent in the response/notification, so you cannot use it for future payments, but the token is still created and associated with the credit card and the payment.

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_i6",
    "Amount": 2000,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "payment product",
    "StatementDescriptor": "bank statement message",
    "Card": {
      "HolderName": "John Doe",
      "Number": "4111111111111111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2021",
      "SecurityCode": "312"
    },		
     "Capture": true,
     "Retry": true,
     "GenerateCreditCardToken": false,
     "Moto": true
  }
}

Response:

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

{
  "Payment": {
    "ID": 202589,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20170511112434",
    "MerchantTransactionID": "s2ptest_i6",
    "OriginatorTransactionID": null,
    "Amount": "2000",
    "Currency": "EUR",
    "CapturedAmount": "2000",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "payment product",
    "StatementDescriptor": "bank statement message",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "VISA-1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2021"
    },
    "CreditCardToken": null,
    "Status": {
      "ID": 11,
      "Info": "Captured",
      "Reasons": []
    },
    "MethodTransactionID": null,
    "AuthorizationCode": "115399",
    "PaymentTokenLifetime": null,
    "Capture": true,
    "Retry": true,
    "RedirectURL": null,
    "3DSecure": false,
    "Fraud": null,
    "Moto": true
  }
}

Hosted Card Form

If you initiate a payment without any card or token details, you will be given in the response a RedirectURL, that will be used to redirect the customer to a form where he will have to fill all the necessary details and continue the payment.

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h6",
    "Amount": 2000,
    "Currency": "EUR",	
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Capture": true
  }
}

Response:

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

{
  "Payment": {
    "ID": 202235,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20161205084804",
    "MerchantTransactionID": "s2ptest_h6",
    "OriginatorTransactionID": null,
    "Amount": "2000",
    "Currency": "EUR",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "StatementDescriptor": null,
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": null,
    "CreditCardToken": null,
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": []
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": 10,
    "Capture": true,
    "Retry": false,
    "RedirectURL": "https://securetest.smart2pay.com/v1/Payments/FillCardDetails?PaymentToken=202235.1010.A3F07F81639486814BAF3319CF96A9071",
    "3DSecure": null
  }
}

Also, if you initiate a Card payment using the CreditCardToken value without the SecurityCode parameter and with the RequireSecurityCode parameter set to true, a RedirectURL will be given in the response. Using this URL the customer will be redirected to a form where the card details are already filled, except the SecurityCode (card number is masked and cannot be changed). The customer will have to fill the value for the SecurityCode parameter and continue the payment.

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_i9",
    "Amount": 2000,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "CreditCardToken": {
      "Value": "F43F90A5CB613D91F704407D4E297EA1",
      "RequireSecurityCode": true
    },		
     "Capture": true,
      "GenerateCreditCardToken": true
   }
}

Response:

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

{
  "Payment": {
    "ID": 202592,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20170511112846",
    "MerchantTransactionID": "s2ptest_i9",
    "OriginatorTransactionID": null,
    "Amount": "2000",
    "Currency": "EUR",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "StatementDescriptor": null,
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "Ends with 1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2018"
    },
    "CreditCardToken": {
      "Value": "F43F90A5CB613D91F704407D4E297EA1"
    },
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": []
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": 10,
    "Capture": true,
    "Retry": false,
    "RedirectURL": "https://securetest.smart2pay.com/v1/Payments/FillCardDetails?PaymentToken=202592.1010.8DBBBF0F45451A5D094F4CDD88E199698",
    "3DSecure": false
  }
}

Whenever the payment process is completed, we will notify you of the event to the notification URL you setup in the Merchant Dashboard. We will send a notification containing the final status of the card payment. For more information about notifications, please go to our section Payment Notification.

One Click Payment

If you initiate a Card payment and you set the GenerateCreditCardToken parameter to true, a token element is sent in the response, containing the value of the newly created credit card token, that you can use for future payments.

The token received in the response, together with the Security Code (CVV) parameter, can be used to initiate future payments, without having to enter all the necessary card details again.

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_i4",
    "Amount": 2000,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "payment product",
    "StatementDescriptor": "bank statement message",
    "CreditCardToken": {
      "Value": "F43F90A5CB613D91F704407D4E297EA1",
      "SecurityCode": "312"
    },		
     "Capture": true,
     "Retry": true,
     "GenerateCreditCardToken": true
  }
}

Response:

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

{
  "Payment": {
    "ID": 202587,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20170511111702",
    "MerchantTransactionID": "s2ptest_i4",
    "OriginatorTransactionID": null,
    "Amount": "2000",
    "Currency": "EUR",
    "CapturedAmount": "2000",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "payment product",
    "StatementDescriptor": "bank statement message",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "Ends with 1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2018"
    },
    "CreditCardToken": {
      "Value": "F43F90A5CB613D91F704407D4E297EA1"
    },
    "Status": {
      "ID": 11,
      "Info": "Captured",
      "Reasons": []
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": true,
    "Retry": true,
    "RedirectURL": null,
    "3DSecure": false
  }
}

Recurring Card Payments

For Recurring Card Payments you will need to generate a credit card token by sending the GenerateCreditCardToken parameter to true and the card details in full in the initial payment request. Afterwards, the recurring card payments will be initiated by sending the new generated token instead of the card details.

Please note that the credit card token has a usage limit that we can set. If the token is sent more times than our set limit the payment will fail.

If you initiate a Card payment and set the GenerateCreditCardToken parameter to true, the CardOnFile object is mandatory to be sent. A token element is sent in the response, containing the value of the newly created credit card token, that will be used to initiate future Recurring Payments.

For more information regarding CardOnFile object please go to our dedicated section Card on file transactions (COF).

    • See below an example of an initial card payment with the GenerateCreditCardToken parameter set to true and mandatory Card details and CardOnFile objects:

      Request:

      POST https://securetest.smart2pay.com/v1/payments
      Authorization: Basic MTAxMDpnYWJp
      
      {
        "Payment": {
          "MerchantTransactionID": "s2ptest_m20",
          "Amount": 1000,
          "Currency": "EUR",
          "ReturnURL": "http://demo.smart2pay.com/redirect.php",   
          "Card": {
            "HolderName": "John Doe",
            "Number": "4548812049400004",
            "ExpirationMonth": "05",
            "ExpirationYear": "2021",
            "SecurityCode": "123",
            "RequireSecurityCode": true
            },
          "GenerateCreditCardToken": true,
          "CardOnFile":{
               "IsInitial": true,
               "TransactionType": "Recurring"
          }
        }
      }

      Response:

      HTTP/1.1 201 Created
      Content-Type: application/json; charset=utf-8
      
      {
        "Payment": {
          "ID": 203747,
          "ClientIP": null,
          "SkinID": null,
          "Created": "20180502085305",
          "MerchantTransactionID": "s2ptest_m20",
          "OriginatorTransactionID": null,
          "Amount": "1000",
          "Currency": "EUR",
          "CapturedAmount": "0",
          "ReturnURL": "http://demo.smart2pay.com/redirect.php",
          "Description": null,
          "StatementDescriptor": null,
          "MethodID": 6,
          "MethodOptionID": null,
          "SiteID": 1010,
          "NotificationDateTime": null,
          "Customer": null,
          "BillingAddress": null,
          "ShippingAddress": null,
          "Articles": null,
          "Card": {
            "HolderName": "John Doe",
            "Number": "Ends with 0004",
            "ExpirationMonth": "05",
            "ExpirationYear": "2021"
            },
          "CreditCardToken": {
            "Value": "C0D510746B513D66093609AA92BDA295"
            },
          "Status": {
            "ID": 9,
            "Info": "Authorized",
            "Reasons": []
            },
          "MethodTransactionID": null,
          "PaymentTokenLifetime": null,
          "Capture": false,
          "Retry": false,
          "RedirectURL": null,
          "3DSecure": false,
          "CardOnFile":{
               "IsInitial": true,
               "TransactionType": "Recurring"
           },
          "Fraud": {
            "Status": "Accept",
            "CheckMode": "CheckOnPreAuthorisation",
            "Score": 31,
            "Reason": "No decision provided"
          }
        }
      }

The token received in the response of the initial payment, together with the RequireSecurityCode parameter set to false, can be used to initiate future Recurring Payments.

For Recurring Payments, the security code is not needed, you only need to send the RequireSecurityCode parameter set to false. In this case, the client will not be redirected to the form page to fill in the security code, but the payment will be directly sent to the upstream processor.
  • See below an example of a Recurring Card Payment:

    Request:

    POST https://securetest.smart2pay.com/v1/payments
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
        "MerchantTransactionID": "s2ptest_m23",
        "Amount": 1000,
        "Currency": "EUR",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "CreditCardToken": {
          "Value": "C0D510746B513D66093609AA92BDA295",
          "RequireSecurityCode": false
          },
        "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring",
              "InitialPaymentID": 203747
        }
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 203751,
        "ClientIP": null,
        "SkinID": null,
        "Created": "20180502090314",
        "MerchantTransactionID": "s2ptest_m23",
        "OriginatorTransactionID": null,
        "Amount": "1000",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": null,
        "StatementDescriptor": null,
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "John Doe",
          "Number": "Ends with 0004",
          "ExpirationMonth": "05",
          "ExpirationYear": "2021"
          },
        "CreditCardToken": {
          "Value": "C0D510746B513D66093609AA92BDA295"
          },
        "Status": {
          "ID": 9,
          "Info": "Authorized",
          "Reasons": []
          },
        "MethodTransactionID": null,
        "PaymentTokenLifetime": null,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": false,
        "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring",
              "InitialPaymentID": 203747
        },
        "Fraud": {
          "Status": "Accept",
          "CheckMode": "CheckOnPreAuthorisation",
          "Score": 31,
          "Reason": "No decision provided"
        }
      }
    }
  • For LATAM region it is mandatory to send in the initial Card payment the Country parameter for the Billing Address together with the Email parameter and the SocialSecurityNumber parameter of the Customer. You also need to set the GenerateCreditCardToken parameter to true and a token element is sent in the response, containing the value of the newly created credit card token.See below an example of an initial card payment with all the mandatory parameters to be sent for LATAM region:

    Request:

    POST https://securetest.smart2pay.com/v1/payments
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
        "MerchantTransactionID": "s2ptest_m21",
        "Amount": 1000,
        "Currency": "EUR",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",   
        "Card": {
          "HolderName": "John Doe",
          "Number": "4548812049400004",
          "ExpirationMonth": "05",
          "ExpirationYear": "2021",
          "SecurityCode": "123",
          "RequireSecurityCode": true
          },
        "GenerateCreditCardToken": true,
        "CardOnFile": {
              "IsInitial": true,
              "TransactionType": "Recurring"
        }
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    
    
    {
      "Payment": {
        "ID": 203746,
        "ClientIP": null,
        "SkinID": null,
        "Created": "20180502085305",
        "MerchantTransactionID": "s2ptest_m20",
        "OriginatorTransactionID": null,
        "Amount": "1000",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": null,
        "StatementDescriptor": null,
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "John Doe",
          "Number": "Ends with 0004",
          "ExpirationMonth": "05",
          "ExpirationYear": "2021"
          },
        "CreditCardToken": {
          "Value": "C0D510746B513D66093609AA92BDA295"
          },
        "Status": {
          "ID": 9,
          "Info": "Authorized",
          "Reasons": []
          },
        "MethodTransactionID": null,
        "PaymentTokenLifetime": null,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": false,
        "CardOnFile": {
              "IsInitial": true,
              "TransactionType": "Recurring"
        },
        "Fraud": {
          "Status": "Accept",
          "CheckMode": "CheckOnPreAuthorisation",
          "Score": 31,
          "Reason": "No decision provided"
        }
      }
    }
    The token received in the response of the initial payment, can be used to initiate future Recurring Payments. See below an example of a Recurring Card Payment for LATAM region:

    Request:

    POST https://securetest.smart2pay.com/v1/payments
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
        "MerchantTransactionID": "s2p_m6",
        "Amount": 10000,
        "Currency": "BRL",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "CreditCardToken": {
          "Value": "F43F90A5CB613D91F704407D4E297EA1"
          },
        "GenerateCreditCardToken": true,
        "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring",
              "InitialPaymentID": 203746
        }
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 203754,
        "ClientIP": null,
        "SkinID": null,
        "Created": "20180430092243",
        "MerchantTransactionID": "s2p_m6",
        "OriginatorTransactionID": null,
        "Amount": "10000",
        "Currency": "BRL",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": null,
        "StatementDescriptor": null,
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "John Doe",
          "Number": "",
          "ExpirationMonth": "05",
          "ExpirationYear": "2021"
          },
        "CreditCardToken": {
          "Value": "F43F90A5CB613D91F704407D4E297EA1"
          },
        "Status": {
          "ID": 9,
          "Info": "Authorized",
          "Reasons": []
          },
        "MethodTransactionID": null,
        "PaymentTokenLifetime": null,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": false,
        "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring",
              "InitialPaymentID": 203746
        },
        "Fraud": {
          "Status": "Accept",
          "CheckMode": "CheckOnPreAuthorisation",
          "Score": 31,
          "Reason": "No decision provided"
        }
      }
    }

Generate a Credit Card Token

To initiate Recurring Card Payments, you must generate first a credit card token. The credit card token can be obtained in two ways:

  • by initiating a payment request with GenerateCreditCardToken parameter set to true. For more detailed information, please go to our section Recurring Card Payments;
  • by using the following action for Card Authentication based on POST HTTP request:

Definition: POST /v1/card/authenticate

By using the Card Authentication request with all the necessary details for customer and for credit card, a token element will be sent in the response, containing the value of the newly created credit card token. The token received in the response can be used to initiate future Recurring Payments.

Request:

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

{
  "CardAuthentication": {
    "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "testing2@test.com",
      "SocialSecurityNumber": "00003456789"
      },
    "BillingAddress": {
      "Country": "BR"
      },
    "Card": {
      "HolderName": "John Doe",
      "Number": "4111111111111111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019",
      "SecurityCode": "312"
    }
  }
}

Response:

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

{
  "CardAuthentication": {
    "Customer": {
      "ID": 0,
      "MerchantCustomerID": null,
      "Email": "testing2@test.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": "00003456789",
      "Phone": null,
      "Company": null
      },
    "BillingAddress": {
      "ID": 0,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "BR"
      },
    "Card": {
      "HolderName": "John Doe",
      "Number": "VISA-1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019"
      },
    "CreditCardToken": {
      "Value": "B531AFAC800FD51A9CCF67D0CC7B24A4",
      "Active": "true"
    },
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

Get information on a specific card token

Definition: GET /v1/card/token/{value}

Where:
  • {value} – the value of the credit card token used for Recurring Payments

You can get more information about a specific credit card token by using an action based on GET HTTP request. Please be aware that only a limited amount of details for each token will be provided.

A 200 HTTP response (OK) is returned if the request was completed successfully.

Request:

GET https://securetest.smart2pay.com/v1/card/token/B531AFAC800FD51A9CCF67D0CC7B24A4
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "CardAuthentication": {                 
    "Card": {
      "HolderName": "John Doe",
      "Number": "VISA-1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019"
    },
    "CreditCardToken": {
      "Value": "B531AFAC800FD51A9CCF67D0CC7B24A4",
      "Active": "true"
    }                            
  }
}

Cancel a Credit Card Token

Definition: POST /v1/card/token/{value}/cancel

Where:
  • {value} – the value of the credit card token used for Recurring Payments

You have the possibility to cancel a credit card token by using the above action.

A 200 HTTP response (OK) is returned if the request was completed successfully.

Request:

POST https://securetest.smart2pay.com/v1/card/token/B531AFAC800FD51A9CCF67D0CC7B24A4/cancel
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "CardAuthentication": { 
    "Card": {
      "HolderName": "John Doe",
      "Number": "VISA-1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019"
    },
    "CreditCardToken": {
      "Value": "B531AFAC800FD51A9CCF67D0CC7B24A4",
      "Active": "false"
    },
    "Status": {
      "ID": 3,
      "Info": "Canceled",
      "Reasons": []
    }
  }
}

Create a payout

Definition: POST /v1/payouts

To initiate a payout, you must create a payout object. The parameters of the payout are sent in the message body as a JSON object. There are two ways in which a payout can be initiated:

  • First one is when you create a payout object with all the necessary card details, like in the below example.

    Request:

    POST https://securetest.smart2pay.com/v1/payouts
    Authorization: Basic MTAxMDpnYWJp
    
    {
     "Payout": {
       "MerchantTransactionID": "test_h4",
       "Amount": 1000,
       "Currency": "EUR",
       "Description": "payment product",
       "Card": {
         "HolderName": "John Doe",
         "Number": "4548812049400004",
         "ExpirationMonth": "02",
         "ExpirationYear": "2029"
        }
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payout": {
        "ID": 214,
        "SiteID": 1010,
        "Created": "20181016133234",
        "MerchantTransactionID": "test_h4",
        "OriginatorTransactionID": null,
        "Amount": "1000",
        "Currency": "EUR",
        "Description": "payment product",
        "StatementDescriptor": null,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": []
        }
      }
    }
  • The second one is when you create a payout object containing only the Credit Card Token that was received in a previous card payment.

    If you initiate a Card payment and you set the GenerateCreditCardToken parameter to true, a token element is sent in the response, containing the value of the newly created credit card token.

    The token received in the response can be used to initiate future payouts.

    Request:

    POST https://securetest.smart2pay.com/v1/payouts
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payout": {
        "MerchantTransactionID": "s2ptest_i11",
        "Amount": "100",
        "Currency": "EUR",
        "Description": "Payout Token Test",    
        "CreditCardToken": {
          "Value": "C0D510746B513D66093609AA92BDA295"
        }
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payout": {
        "ID": 219,
        "SiteID": 1010,
        "Created": "20190612130707",
        "MerchantTransactionID": "s2ptest_i11",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "Description": "Payout Token Test",
        "StatementDescriptor": null,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": []
        }
      }
    }

In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

Request:

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

{
  "Payout": {
    "MerchantTransactionID": "test_h5",
    "Amount": 1000,
    "Currency": "EUR",
    "Description": "payment product"
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "InvalidRequestID": "i3355",
    "ID": null,
    "SiteID": 1010,
    "Created": null,
    "MerchantTransactionID": "test_h5",
    "OriginatorTransactionID": null,
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "payment product",
    "StatementDescriptor": null,
    "Status": {
      "ID": null,
      "Info": null,
      "Reasons": [
      {
        "Code": 1206,
        "Info": "CardDetails are missing"
        }
      ]
    }
  }
}

Card Payout Notification

We will notify you about the new status of the payout to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

You need to respond with HTTP code 204 (No Content)!

Payout notification format:

Authorization: Basic MTAxMDpnYWJp

{
  "Payout": {
    "ID": 214,
    "SiteID": 1010,
    "Created": "20181016133234",
    "MerchantTransactionID": "test_h4",
    "OriginatorTransactionID": null,
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "payment product",
    "StatementDescriptor": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

Response:

204 No Content

Get information on a specific payout

You can get information about a payout by using GET HTTP request.

Definition: GET /v1/payouts/{id}

Where:
  • {id} – GlobalPay Payout ID

Request:

GET https://securetest.smart2pay.com/v1/payouts/214
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 214,
    "SiteID": 1010,
    "Created": "20181016133234",
    "MerchantTransactionID": "test_h4",
    "OriginatorTransactionID": null,
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "payment product",
    "StatementDescriptor": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

Get the status of a payout

You can get the status of a payout by using the following GET HTTP request.

Please note that this method sends only the status information about a payout. To receive more information about a payout please go to our section Get information on a specific payout.

Definition: GET /v1/payouts/{id}/status

Where:
  • {id} – GlobalPay Payout ID

Request:

GET https://securetest.smart2pay.com/v1/payouts/214/status
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 214,
    "MerchantTransactionID": "test_h4",
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

Get a list of payouts

Without specifying any parameters a list of payouts is returned. Please be aware that only a limited amount of details for each payout will be provided.

Definition: GET /v1/payouts

Request:

GET https://securetest.smart2pay.com/v1/payouts
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payouts": [
        {
            "ID": 214,
            "SiteID": 1010,
            "Created": "20181016133234",
            "MerchantTransactionID": "test_h4",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 213,
            "SiteID": 1010,
            "Created": "20181016133041",
            "MerchantTransactionID": "Laur-1539696641",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 212,
            "SiteID": 1010,
            "Created": "20181016133024",
            "MerchantTransactionID": "Laur-1539696624",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 4,
                "Info": "Failed",
                "Reasons": [
                    {
                        "Code": 5065,
                        "Info": "Card not found within table of ranges."
                    }
                ]
            }
        },
        {
            "ID": 211,
            "SiteID": 1010,
            "Created": "20181016132837",
            "MerchantTransactionID": "Laur-1539696517",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": []
            }
        },
        {
            "ID": 210,
            "SiteID": 1010,
            "Created": "20181016123606",
            "MerchantTransactionID": "Laur-1539693367",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": []
            }
        },
        {
            "ID": 209,
            "SiteID": 1010,
            "Created": "20181016123450",
            "MerchantTransactionID": "Laur-1539693291",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": []
            }
        }
    ]
}

Get a list of payouts (filtered)

You can specify various filters as parameters in the query string in order to get a customized list of payouts.

Requests:

GET https://securetest.smart2pay.com/v1/payouts?limit=3
Authorization: Basic MTAxMDpnYWJp
GET https://securetest.smart2pay.com/v1/payouts?maximumAmount=1000
Authorization: Basic MTAxMDpnYWJp

The following table describes the possible filters you can use. You can mix the filters so you can obtain the desired results.

FILTERS
Field Description Data type
limit The maximum number of items that will be returned Long
offset A list of payments starting with the value of the offset parameter will be returned. The offset parameter can also be used together with the limit parameter to select specific entries within a list of payments. String
startDate The date and time after which the payments are returned DateTime

(YYYYMMDDHHMMSS)

endDate The date and time until which the payments are returned DateTime

(YYYYMMDDHHMMSS)

country Only the transactions having this country code will be returned String

(ISO 3166-1-alpha-2)

currency Only the transactions having this currency code will be returned String

(ISO 4217)

minimumAmount Only the payments with an amount higher than this will be returned Integer (last 2 digits representing the decimal part)
maximumAmount Only the payments with an amount lower than this will be returned Integer (last 2 digits representing the decimal part)
merchantTransactionID Only the payment having this merchantTransactionID will be returned String

^[0-9a-zA-Z_-]{1,50}$

statusID Only the transactions having this statusID will be returned. Integer

The ID of the payment status can have the following values: 1 – Open, 2 – Success, 3 – Cancelled, 4 – Failed, 5 – Expired, 9 – Authorized.

methodTransactionID Only the payments having this methodTransactionID will be returned. This transaction ID from the payment method provider can be used for customer support. String

^[0-9a-zA-Z_-]{1,50}$

Here is an example of a request with the limit filter set to 3. This means that it will only return 3 transactions in a descending order.

Request:

GET https://securetest.smart2pay.com/v1/payouts?limit=3
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payouts": [
        {
            "ID": 214,
            "SiteID": 1010,
            "Created": "20181016133234",
            "MerchantTransactionID": "test_h4",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 213,
            "SiteID": 1010,
            "Created": "20181016133041",
            "MerchantTransactionID": "Laur-1539696641",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 212,
            "SiteID": 1010,
            "Created": "20181016133024",
            "MerchantTransactionID": "Laur-1539696624",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 4,
                "Info": "Failed",
                "Reasons": [
                    {
                        "Code": 5065,
                        "Info": "Card not found within table of ranges."
                    }
                ]
            }
        }
    ]
}

You can also mix various filters to get specific results. Here is an example of a request with the limit filter set to 2 and the currency EUR. This means that it will return the last two payout entries that have the transaction currency EUR.

Request:

GET https://securetest.smart2pay.com/v1/payouts?limit=2&currency=EUR
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payouts": [
        {
            "ID": 214,
            "SiteID": 1010,
            "Created": "20181016133234",
            "MerchantTransactionID": "test_h4",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 213,
            "SiteID": 1010,
            "Created": "20181016133041",
            "MerchantTransactionID": "Laur-1539696641",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        }
    ]
}

Fraud Management

We are providing you with a secure and reliable Fraud Management solution that will protect you from any fraudulent activity and keep you and your customers happy and safe. The Fraud Check system will verify and validate your transactions in order to detect any suspicious transactions and therefore reduce the risk of chargebacks.

There are 3 possible scenarios when initiating a card payment with Fraud Check system on:

  • The card payment is initiated and the Fraud Check system doesn’t detect any suspicious behavior or rule. The payment is accepted. For more details checkout our section: Fraud Check – Payment Accepted.

  • The card payment is initiated and the Fraud Check system detects a suspicious behavior or rule. The payment is denied. For more details checkout our section: Fraud Check – Payment Denied.

  • The card payment is initiated and the Fraud Check system detects a possible suspicious behavior or rule. The payment is challenged by the fraud check provider. You can reject or accept the challenge. For more details checkout our section: Fraud Check – Payment Challenged.

Fraud Check – Payment Accepted

Any credit card transaction will undergo a Fraud Check based on the provided parameters. The more parameters are provided, a more accurate precision the fraud check will have.

The card payment is initiated and the Fraud Check system doesn’t detect any suspicious behavior or rule. The payment is accepted.

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_j9",
    "Amount": 100,
    "Currency": "BRL",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "BillingAddress": {
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "BR"
    },
    "ShippingAddress": null,
    "Customer": {
      "FirstName":"John",
      "LastName":"Doe",
      "Email": "accept@accept.com",
      "SocialSecurityNumber": "00003456789"
    },
    "Card": {
      "HolderName": "John Doe",
      "Number": "4111111111111111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019",
      "SecurityCode": "312"
    },
    "Installments": 3,
    "Capture": false,
    "Retry": false,
    "GenerateCreditCardToken": false,
    "PaymentTokenLifetime": 100,
    "3DSecure": false,
    "Language": "ro-RO",
    "SkinID": 200
  }
}

Response:

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

{
  "Payment": {
    "ID": 203372,
    "ClientIP": null,
    "SkinID": 200,
    "Created": "20180209082328",
    "MerchantTransactionID": "s2ptest_j9",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 297,
      "MerchantCustomerID": null,
      "Email": "accept@accept.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": "00003456789",
      "Phone": null,
      "Company": null
      },
    "BillingAddress": {
      "ID": 9590,
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "BR"
      },
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "Ends with 1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019"
      },
    "CreditCardToken": null,
    "Status": {
      "ID": 9,
      "Info": "Authorized",
      "Reasons": []
      },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": false,
    "Retry": false,
    "RedirectURL": null,
    "3DSecure": false,
    "Fraud": {
      "Status": "Accept",
      "CheckMode": "CheckOnPreAuthorisation",
      "Score": 0,
      "Reason": "Always accept rule"
      },
    "Installments": 3
    }
}   

Fraud Check – Payment Denied

If the system detects a malicious transaction, that transaction will be rejected by the fraud check provider. You will be given in the response the reason of why the transaction has Failed in the Reason field in the Fraud object.

The card payment is initiated and the Fraud Check system detects a suspicious behavior or rule. The payment is denied.

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_j8",
    "Amount": 100,
    "Currency": "BRL",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "BillingAddress": {
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "BR"
    },
    "ShippingAddress": null,
    "Customer": {
      "FirstName":"John",
      "LastName":"Doe",
      "Email": "deny@deny.com",
      "SocialSecurityNumber": "00003456789"
    },
    "Card": {
      "HolderName": "John Doe",
      "Number": "4111111111111111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019",
      "SecurityCode": "312"
    },
    "Installments": 3,
    "Capture": false,
    "Retry": false,
    "GenerateCreditCardToken": false,
    "PaymentTokenLifetime": 100,
    "3DSecure": false,
    "Language": "ro-RO",
    "SkinID": 200
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": 203371,
    "ClientIP": null,
    "SkinID": 200,
    "Created": "20180209082141",
    "MerchantTransactionID": "s2ptest_j8",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 296,
      "MerchantCustomerID": null,
      "Email": "deny@deny.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": "00003456789",
      "Phone": null,
      "Company": null
      },
    "BillingAddress": {
      "ID": 9590,
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "BR"
      },
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "Ends with 1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019"
      },
    "CreditCardToken": null,
    "Status": {
      "ID": 4,
      "Info": "Failed",
      "Reasons": [
        {
          "Code": 116,
          "Info": "Transaction rejected by fraud provider"
          }
        ]
      },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": false,
    "Retry": false,
    "RedirectURL": null,
    "3DSecure": false,
    "Fraud": {
      "Status": "Reject",
      "Score": 74,
      "Reason": "Transaction hit a velocity or rule threshold"
      },
    "Installments": 3
    }
}

Fraud Check – Payment Challenged

If the system detects a possible malicious transaction, that transaction will be challenged by the fraud check provider. There are 2 possible outcomes after running your own processes and procedures for fraud management: you can reject or accept the challenge.

The card payment is initiated and the Fraud Check system detects a possible suspicious behavior or rule. The payment is challenged by the fraud check provider. You can reject or accept the challenge.

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_j10",
    "Amount": 100,
    "Currency": "BRL",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "BillingAddress": {
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "BR"
    },
    "ShippingAddress": null,
    "Customer": {
      "FirstName":"John",
      "LastName":"Doe",
      "Email": "challenge@challenge.com",
      "SocialSecurityNumber": "00003456789"
    },
    "Card": {
      "HolderName": "John Doe",
      "Number": "4111111111111111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019",
      "SecurityCode": "312"
    },
    "Installments": 3,
    "Capture": false,
    "Retry": false,
    "GenerateCreditCardToken": false,
    "PaymentTokenLifetime": 100,
    "3DSecure": false,
    "Language": "ro-RO",
    "SkinID": 200
  }
}

Response:

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

{
  "Payment": {
    "ID": 203373,
    "ClientIP": null,
    "SkinID": 200,
    "Created": "20180209082529",
    "MerchantTransactionID": "s2ptest_j10",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 298,
      "MerchantCustomerID": null,
      "Email": "challenge@challenge.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": "00003456789",
      "Phone": null,
      "Company": null
      },
    "BillingAddress": {
      "ID": 9590,
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "BR"
      },
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "Ends with 1111",
      "ExpirationMonth": "02",
      "ExpirationYear": "2019"
      },
    "CreditCardToken": null,
    "Status": {
      "ID": 30,
      "Info": "PendingChallengeConfirmation",
      "Reasons": []
      },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": false,
    "Retry": false,
    "RedirectURL": null,
    "3DSecure": false,
    "Fraud": {
      "Status": "Challenge",
      "Score": 55,
      "Reason": "Transaction hit a velocity or rule threshold"
      },
    "Installments": 3
    }
}

Accept the Challenge:

Request:

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

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": 203373,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20180209082529",
    "MerchantTransactionID": "s2ptest_j10",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "411111******1111",
      "ExpirationMonth": "2",
      "ExpirationYear": "2019"
      },
    "CreditCardToken": null,
    "Status": {
      "ID": 9,
      "Info": "Authorized",
      "Reasons": []
      },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": false,
    "Retry": false,
    "RedirectURL": null,
    "3DSecure": false,
    "Fraud": {
      "Status": "Challenge",
      "Score": 55,
      "Reason": "Transaction hit a velocity or rule threshold"
      },
    "Installments": 3
    }
}

Reject the Challenge:

Request:

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

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": 203374,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20180209082726",
    "MerchantTransactionID": "s2ptest_j11",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "BRL",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "test payment",
    "StatementDescriptor": "card payment",
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 298,
      "MerchantCustomerID": null,
      "Email": "challenge@challenge.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": "00003456789",
      "Phone": null,
      "Company": null
      },
    "BillingAddress": {
      "ID": 9590,
      "City": "Iasi",
      "ZipCode": "7000-49",
      "State": "Iasi",
      "Street": "Sf Lazar",
      "StreetNumber": "37",
      "HouseNumber": "5A",
      "HouseExtension": "-",
      "Country": "BR"
      },
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "411111******1111",
      "ExpirationMonth": "2",
      "ExpirationYear": "2019"
      },
    "CreditCardToken": null,
    "Status": {
      "ID": 3,
      "Info": "Cancelled",
      "Reasons": [
      {
        "Code": 118,
        "Info": "Transaction rejected by merchant"
        }
      ]
    },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": null,
    "Capture": false,
    "Retry": false,
    "RedirectURL": null,
    "3DSecure": false,
    "Fraud": {
      "Status": "Challenge",
      "Score": 55,
      "Reason": "Transaction hit a velocity or rule threshold"
      },
    "Installments": 3
    }
}

PSD2 and Strong Customer Authentication (SCA)

The Second Payment Services Directive (PSD2), a set of laws and regulations for payment services in the European Union (EU) and the European Economic Area (EEA), has come with a lot of implications for marketplace business models already, and it will expand further more on all companies in Europe that deal with payments, ranging from how to regulate the emergence of Third Party Providers (TPPs) to the need for strong customer authentication (SCA).

Strong Customer Authentication (SCA) will come into effect on 14 September 2019, so there is little time for merchants to start updating their integration to prepare for it. Transactions that don’t follow the new authentication guidelines may be declined by the banks.

Strong Customer Authentication (SCA) has to be applied when all of the conditions below are met:

  • The business is based in the European Economic Area (EEA);
  • The customers are from EEA area;
  • The payment is initiated online by the customer.

SCA requires merchants to integrate into the checkout flow a two-factor authentication that is based on the use of two or more elements categorised as:

  • knowledge (something only the user knows, i.e password);
  • possession (something only the user possesses: i.e.,phone, token, certificate tec.);
  • inherence (something the user is: i.e. fingerprint, Face ID).

For an authentication to meet the criteria of the PSD2, it must combine at least 2 of these 3 factors. To strongly authenticate an online payment, for example, consumers will be required to use their phone (something you own) and authenticate via fingerprint (something you are).

As of September 14, the credit card number alone will no longer be considered as a valid authentication method and additional factors that meet the requirements of PSD2, such as biometric data, need to be added in the authentication process.

The 3D Secure version 1.0 authentication method used for credit card payments is being updated to version 2.0, which is the best measure to meet the above compliance criteria.

Apart from these cases there are a few exemptions to SCA, but keep in mind that banks can choose to not honor these exemptions and you need to be prepared to handle a SCA challenge even if the transactions has been submitted under one of the exemptions.

Below is the list with the most relevant ones. For more detailed information, check out our dedicated section Exemptions to Strong Customer Authentication (SCA).

Exemptions to Strong Customer Authentication (SCA)
Exemption Description
Low Value Small amounts less than 30 EUR: For a transaction of less than 30 EUR and up to 100 EUR accumulated or up to 5 transactions since the last SCA. Beyond 100 EUR or beyond 5 unauthenticated transactions, a new SCA is required. Keep in mind that since the information needed to validate these stipulations is only available to the issuing bank, you will still need to confirm if SCA is required on all transactions that might fall into this exemption category.
Low Risk / TRA Transactional Risk Analysis: SCA can be deactivated for online payments between €30 and €500, depending on the payment providers fraud rates (see table below). There are no low-risk exemptions for transactions over €500. Merchants have to rely on a payment service provider (e.g. an acquirer) to act upon their request. In addition, the test to trigger the exemption rests with whether the PSP satisfies the prescribed conditions, not the merchants themselves. Smart2Pay keeps a very low fraud rate by using state of the art anti-fraud solutions such as RedShield, Machine Learning algorithms and by working with low risk acquiring banks which have very good fraud scores.
MIT Merchant Initiated Transaction (MIT): are payment transactions that are not initiated by the payer but by the payee only and are not subject to strong customer authentication (SCA) to the extent that these transactions are initiated without any interaction or involvement of the payer. MIT transactions are subjected to SCA except when a mandate is signed by the client. For example, SEPA Direct Debits are initiated by the merchant but have a direct debit mandate signed by the end customer. Thus, SCA is not applicable in this case and there are no restrictions to the frequency or the amount (obtained scheme transaction identifier needs to be provided for use in the subsequent transactions).
Trusted Beneficiaries Payment to a trusted beneficiary: Customers can add their preferred online sellers to a list of trusted beneficiaries held by the issuing bank, so that they don’t required to authenticate for each new payment. Please instruct your customers if possible to add your business to the white-list at their bank.
Secure Corporate payments SCA can de deactivated for corporate card payments made through secure processes and protocols initiated by businesses and not available for consumers. Payments that are included in this category are those made through central travel accounts, lodged cards, virtual cards, and secure corporate cards, like the ones used in a corporate travel management system.

Please check out our page again soon where we will keep you posted on any updates regarding 3D Secure version 2.0.

Exemptions to Strong Customer Authentication (SCA)

With the Second Payment Services Directive (PSD2), the new set of laws and regulations for payment services in the European Union (EU) and the European Economic Area (EEA), Strong Customer Authentication (SCA) will be the requirement for all online transactions. However, there are still some exemptions from this rule where specific types of low-risk payments may be still exempted from Strong Customer Authentication (SCA).

Please keep in mind that banks can choose not to honor these exemptions and you need to be prepared to handle a SCA challenge even if the transactions has been submitted under one of the below exemptions.

The most relevant SCA exemptions are:

  • MIT
  • Low Risk / TRA
  • Low Value
  • Secure Corporate payments
  • Trusted Beneficiaries

1. Merchant Initiated Transaction (MIT)

MITs are payment transactions that are not initiated by the payer but by the payee only and are not subject to strong customer authentication (SCA) to the extent that these transactions are initiated without any interaction or involvement of the payer. MIT transactions are subjected to SCA except when a mandate is signed by the client. For example, SEPA Direct Debits are initiated by the merchant but have a direct debit mandate signed by the end customer. Thus, SCA is not applicable in this case and there are no restrictions to the frequency or the amount (obtained scheme transaction identifier needs to be provided for use in the subsequent transactions).

Adjustment of initial Authorisation allows merchants to increase or decrease the authorised amount after the initial authorisation has taken place is also MIT. This enables tipping.

2. TRA – Transactional Risk Analysis

SCA can be deactivated for online payments between €30 and €500, depending on the payment providers fraud rates (see table below). There are no low-risk exemptions for transactions over €500. Merchants have to rely on a payment service provider (e.g. an acquirer) to act upon their request. In addition, the test to trigger the exemption rests with whether the PSP satisfies the prescribed conditions, not the merchants themselves. Smart2Pay keeps a very low fraud rate by using state of the art anti-fraud solutions such as RedShield, Machine Learning algorithms and by working with low risk acquiring banks which have very good fraud scores.

Adding additional information in the payment request will maximize the probability of getting the exemption by Issuers. The chargeback liability shifts to the issuer as well.

Regulatory Technical Standards (RTS), that payment providers need to take into account through real-time risk analysis, covers the following:

  • abnormal spending or behavioral pattern of the payer;
  • unusual information about the payer’s device/software access;
  • malware infection in any session of the authentication procedure;
  • known fraud scenario in the provision of payment services;
  • abnormal location of the payer;
  • high-risk location of the payee.

The fraud rate limits for payment providers are being applied as follows:

Fraud rate and amount limits
Fraud transaction rate Amount limits
Up to 0.01% Up to €500
Up to 0.06% Up to €250
Up to 0.13% Up to €100

3. Low value: Small amounts less than 30 EUR

For a transaction of less than 30 EUR and up to 100 EUR accumulated or up to 5 transactions since the last SCA. Beyond 100 EUR or beyond 5 unauthenticated transactions, a new SCA is required. Keep in mind that since the information needed to validate these stipulations is only available to the issuing bank, you will still need to confirm if SCA is required on all transactions that might fall into this exemption category.

4. Payment to a trusted beneficiary

Customers can add their preferred online sellers to a list of trusted beneficiaries held by the issuing bank, so that they don’t required to authenticate for each new payment. Please instruct your customers if possible to add your business to the white-list at their bank.

5. Secure Corporate payments

SCA can de deactivated for corporate card payments made through secure processes and protocols initiated by businesses and not available for consumers. Payments that are included in this category are those made through central travel accounts, lodged cards, virtual cards, and secure corporate cards, like the ones used in a corporate travel management system.

See below an example of a MerchantInitiatedTransaction (MIT) transaction type:

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_m10",
    "Amount": 1000,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",   
    "Card": {
      "HolderName": "John Doe",
      "Number": "4548812049400004",
      "ExpirationMonth": "05",
      "ExpirationYear": "2021",
      "SecurityCode": "123"     
      },
     "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": "MerchantInitiatedTransaction"
  }
}

There are 2 possible response scenarios:

  • Exemption is approved: The cardholder’s bank receives the request, assesses the risk level of the transaction, and approves the exemption and the SCA is no more necessary. The payment has status Authorized / Captured in the response.

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 172498,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190913075654",
        "MerchantTransactionID": "s2ptest_m10",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
       "Description": "silviu test",
        "StatementDescriptor": "Static 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": "05",
          "ExpirationYear": "2021"
        },
        "CreditCardToken": null,
        "Status": {
          "ID": 9,
          "Info": "Authorized",
          "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "971896",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": true,
        "3DSecureData": null,   
        "ScaExemption": "MerchantInitiatedTransaction",
        "CardOnFile": null,
        "Fraud": null
      }
    }
    

  • Exemption is rejected: The cardholder’s bank receives the request, assesses the risk level of the transaction, and rejectes the exemption and the SCA is mandatory. The payment has status Open in the response. The customer accesses the RedirectURL form the response and is redirected to the 3D Secure page to authenticate the transaction.

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payment": {
        "ID": 172498,
        "ClientIP": null,
        "SkinID": 200,
        "Created": "20190913075654",
        "MerchantTransactionID": "s2ptest_m10",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "silviu test",
        "StatementDescriptor": "Static Description",
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "Test Person",
          "Number": "VISA-6852",
          "ExpirationMonth": "05",
          "ExpirationYear": "2020"
        },
        "CreditCardToken": null,
        "Status": {
          "ID": 1,
          "Info": "Open",
          "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": null,
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "Retry": false,
        "RedirectURL": "http://85.186.26.139:58938/v1/Payments/FillCardDetails?PaymentToken=172500.1006.5CD50C1B1707FB83EAA7655F9B21D42E9&SkipLandingPage=true",
        "3DSecure": true,
        "3DSecureData": null,   
        "ScaExemption": "MerchantInitiatedTransaction",
        "CardOnFile": null,
        "Fraud": null
      }
    }

Card on file transactions (COF)

A card-on-file transaction is a transaction where a cardholder authorizes a merchant to store the cardholder’s payment details, and also authorizes that same merchant to bill the cardholder’s stored account.

Transactions are either initiated by a consumer, or by a merchant based on the instructions given to them by the consumer. It is possible for a merchant to initiate a transaction without consumer action.

Consumer-Initiated Transactions (CIT): where the consumer is present and provides their payment credentials. This can be through a terminal in-store, or online through a checkout experience. A consumer-initiated transaction contains proof (such as track data, chip data with cryptograms, cardholder verification methods, and online through the presence of Card Verification Value 2 (CVV2) or Verified by Visa (VBV) authentication data) that the cardholder was involved in the transaction.

Merchant-Initiated Transactions (MIT): a transaction that depends to a previous consumer-initiated transaction, but it is conducted without the consumer being present and without any additional cardholder validation performed. It’s a transaction based on a previous agreement between the consumer and the merchant for a recurring product or service or an automated billing or unscheduled transactions etc.

Don’t miss out the below examples with CardOnFile object used for the initial transaction and also for a subsequent one.

Card On File (COF) Transaction Types
Type Description
Installments Deferred payment. Always referring to an INDIVIDUAL purchase, the amount of the several transactions is fixed, and with a definite time interval.
Recurring Recurring payment. The amount of transactions can be fixed or variable, and with a defined time interval.
Reauthorization Normally before partial shipments. Also, when the client extends the stay in hotel / rental of the vehicle or when, having an estimated authorization, the final amount is requested (“settlement”).
Resubmission Original denied because of “balance”; only for certain sectors of activity (for more details check the regulations of the brands) and with a maximum number of days from the purchase. Relevant example:”Transport”.
Delayed Those that happen after the transaction for services rendered / used unknown at the beginning. (Minibar, vehicle damage, fines ….)
Incremental When additional services are incurred during the contract period.
No Show When the merchant charges services to which the owner committed, but then failed to comply with the agreed terms. Relevant example: unattended reservations at hotels without cancellation.
Other The rest of COF transactions that do not fit with any of the previous ones.
  • For an initial transaction from a subsequent payments chain the IsInitial parameter from CardOnFile object needs to be set to true.

    Request:

    POST https://securetest.smart2pay.com/v1/payments
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
      "MerchantTransactionID": "s2ptest_11a",
      "Amount": "100",
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "Test Description",
      "StatementDescriptor1": "Dynamic Test Description",
      "Card": {
        "HolderName": "Test Person",
        "Number": "4012005162084369",
        "ExpirationMonth": "05",
        "ExpirationYear": "2020",
        "SecurityCode": "123",
        "RequireSecurityCode": true
        },
      "Capture": false,
      "Retry": 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"
        },
      "CardOnFile":{
             "IsInitial": true,
             "TransactionType": "Recurring"
          },
      "Language": "ro-RO",
      "SkinID": 200
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 1234,
            "ClientIP": null,
            "SkinID": 200,
            "Created": "20190828091954",
            "MerchantTransactionID": "s2ptest_11a",
            "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": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Card": {
                "HolderName": "Test Person",
                "Number": "VISA-4369",
                "ExpirationMonth": "05",
                "ExpirationYear": "2020"
            },
            "CreditCardToken": null,
            "Status": {
                "ID": 9,
                "Info": "Authorized",
                "Reasons": []
            },
            "MethodTransactionID": null,
            "AuthorizationCode": "591659",
            "PaymentTokenLifetime": 10,
            "Capture": false,
            "Retry": 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,
            "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring"
            },
            "Fraud": {
                "Status": "Accept",
                "Score": 31,
                "Reason": "No decision provided"
            }
        }
    }

  • Transaction that depends to the previous consumer-initiated transaction. For a transaction from a subsequent payments chain the IsInitial parameter from CardOnFile object needs to be set to false.For subsequent payments always send in the request the InitialPaymentID parameter in the CardOnFile object.

    Request:

    POST https://securetest.smart2pay.com/v1/payments
    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
      "MerchantTransactionID": "s2ptest_12a",
      "Amount": "100",
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "Test Description",
      "StatementDescriptor1": "Dynamic Test Description",
      "Card": {
        "HolderName": "Test Person",
        "Number": "4012005162084369",
        "ExpirationMonth": "05",
        "ExpirationYear": "2020",
        "SecurityCode": "123",
        "RequireSecurityCode": true
        },
      "Capture": false,
      "Retry": 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": "MerchantInitiatedTransaction",
      "CardOnFile":{
        "IsInitial": false,
        "TransactionType": "Recurring",
        "InitialPaymentID": 1234        
        },
      "Language": "ro-RO",
      "SkinID": 200
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 12345,
            "ClientIP": null,
            "SkinID": 200,
            "Created": "20190828091954",
            "MerchantTransactionID": "s2ptest_12a",
            "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": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Card": {
                "HolderName": "Test Person",
                "Number": "VISA-4369",
                "ExpirationMonth": "05",
                "ExpirationYear": "2020"
            },
            "CreditCardToken": null,
            "Status": {
                "ID": 9,
                "Info": "Authorized",
                "Reasons": []
            },
            "MethodTransactionID": null,
            "AuthorizationCode": "591659",
            "PaymentTokenLifetime": 10,
            "Capture": false,
            "Retry": 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": "MerchantInitiatedTransaction",
            "CardOnFile": {
              "IsInitial": false,
              "TransactionType": "Recurring",
              "InitialPaymentID": 1234
              },
            "Fraud": {
                "Status": "Accept",
                "Score": 31,
                "Reason": "No decision provided"
            }
        }
    }

3D Secure

3D Secure is a security protocol used as an additional layer of security for online credit card transactions prior to authorization in order to prevent fraud. 3D Secure comes from the three-domain model used to provide the additional layer of secure authentication between the financial authorization process and online authentication process. The service is provided by Visa and MasterCard under the name Verified by Visa and MasterCard SecureCode.

3D Secure 1.0 enables customers to validate transactions they make over the internet by requesting an authentication method (usually a a password-based method sent over mobile or email address is used), thus reducing the risk of fraudulent use by unauthorized individuals.

Although the introduction of 3D Secure 1.0 has helped merchants fight fraud, it also came with a negative impact on the user experience, adding extra steps and supporting only browser-based transactions.

This is why the new 3D Secure 2.0 has come into effect to answer and to resolve the security issues and to implement the strong customer authentication (SCA).

SCA requires merchants to integrate into the checkout flow a two-factor authentication that is based on the use of two or more elements categorised as:
  • knowledge (something only the user knows, i.e password);
  • possession (something only the user possesses: i.e.,phone, token, certificate tec.);
  • inherence (something the user is: i.e. fingerprint, Face ID).
For more information about the PSD2 Directive and Strong Customer Authentication (SCA) visit our section: PSD2 and Strong Customer Authentication (SCA).

3D Secure 1.0 Payments

For enabling and using 3D Secure service, there are two options:

  • statically, in which we can enable for you the 3D Secure service at SiteID level;
  • dynamically, in which you send the 3DSecure parameter in the payment request.

If you set the 3DSecure parameter to true, the customer will be required to authenticate the card used for that transaction:

Request:

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

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_1002",
    "Amount": 100,
    "Currency": "EUR",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "S2P 3Dsecure test",    
    "Card": {
      "HolderName": "John Doe",
      "Number": "4548812049400004",
      "ExpirationMonth": "05",
      "ExpirationYear": "2021",
      "SecurityCode": "123"
      },
    "3DSecure": true
  }
}

Response:

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

{
  "Payment": {
    "ID": 203771,
    "ClientIP": null,
    "SkinID": null,
    "Created": "20180509114444",
    "MerchantTransactionID": "s2ptest_1002",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "CapturedAmount": "0",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "S2P 3Dsecure test",
    "StatementDescriptor": null,
    "MethodID": 6,
    "MethodOptionID": null,
    "SiteID": 1010,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Card": {
      "HolderName": "John Doe",
      "Number": "Ends with 0004",
      "ExpirationMonth": "05",
      "ExpirationYear": "2021"
      },
    "CreditCardToken": null,
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": []
      },
    "MethodTransactionID": null,
    "PaymentTokenLifetime": 10,
    "Capture": false,
    "Retry": false,
    "RedirectURL": "https://securetest.smart2pay.com/v1/Payments/FillCardDetails?PaymentToken=203771.1010.05D9FE3FD0AF7FD3D1C848A82F5F54985&SkipLandingPage=true",
    "3DSecure": true,
    "3DSecureData": {     
      "AuthenticationStatus": "Y",
      "ECI": "05",
      "CAVV": "MDA5ODYyNjQxMzEyNzQxMTQ4NzA=",
      "DSID": "f41f41f-f412f-41f-4321-f4132f4",
      "3DSecureVersion": "1.0.2"
    },
    "Fraud": null
  }
}

Access the RedirectURL received in the payment response and enter an identification code. Please note that the landing page will be different depending on the card issuer.

For test purposes, please enter the identification test code received on the page (123456). For a Success 3D Secure Authentication click on the Acceptar button and for a Failed 3D Secure Authentication click on the Cancelar button.

1 Enter Identification Code

You will receive a payment notification to the Notification URL you setup in the Merchant Dashboard containing the new payment status. For more information on Payment Notifications with Success or Failed 3D Secure Authentication, go to our section 3D Secure Payment 1.0 Notification.

3D Secure 1.0 Payment Notification

We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.
  • For a payment with Success 3D Secure Authentication, you will receive the below notification:

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
        "ID": 203771,
        "ClientIP": null,
        "SkinID": null,
        "Created": "20180509114444",
        "MerchantTransactionID": "s2ptest_1002",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "S2P 3Dsecure test",
        "StatementDescriptor": null,
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 1010,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "John Doe",
          "Number": "Ends with 0004",
          "ExpirationMonth": "5",
          "ExpirationYear": "2021"
        },
        "CreditCardToken": null,
        "Status": {
          "ID": 9,
          "Info": "Authorized",
          "Reasons": []
        },
        "MethodTransactionID": null,
        "PaymentTokenLifetime": null,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": true,
        "Fraud": null
      }
    }
    

    Response:

    204 No Content
  • For a Failed 3D Secure Authentication, you will receive the below notification:

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MTAxMDpnYWJp
    
    {
      "Payment": {
        "ID": 203772,
        "ClientIP": null,
        "SkinID": null,
        "Created": "20180509114626",
        "MerchantTransactionID": "s2ptest_1003",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": "0",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "S2P 3Dsecure test",
        "StatementDescriptor": null,
        "MethodID": 6,
        "MethodOptionID": null,
        "SiteID": 10101,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Card": {
          "HolderName": "John Doe",
          "Number": "Ends with 0004",
          "ExpirationMonth": "5",
          "ExpirationYear": "2021"
        },
        "CreditCardToken": null,
        "Status": {
          "ID": 4,
          "Info": "Failed",
          "Reasons": [
            {
              "Code": "5073",
              "Info": "Error in holder authentication"
            }
          ]
        },
        "MethodTransactionID": null,
        "PaymentTokenLifetime": null,
        "Capture": false,
        "Retry": false,
        "RedirectURL": null,
        "3DSecure": true,
        "Fraud": null
      }
    }

    Response:

    204 No Content

3D Secure 2.0 Payments

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": "4012005162084369",
    "ExpirationMonth": "05",
    "ExpirationYear": "2020",
    "SecurityCode": "123",
    "RequireSecurityCode": true
    },
  "Capture": false,
  "Retry": 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
  }
}

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-4369",
            "ExpirationMonth": "05",
            "ExpirationYear": "2020"
        },
        "CreditCardToken": null,
        "Status": {
            "ID": 9,
            "Info": "Authorized",
            "Reasons": []
        },
        "MethodTransactionID": null,
        "AuthorizationCode": "591659",
        "PaymentTokenLifetime": 10,
        "Capture": false,
        "Retry": 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"
        }
    }
}