Skip to main content
knowledgecenter.2checkout.com

Payment flow with Credit Cards

Overview

The following payment methods are supported for the Credit/debit cards with 3DS flow: Visa, Visa Electron, Mastercard, Maestro, American Express, JCB, Diners Club, Discover, UnionPay, Dankort.

While 3DS related fields were not mandatory for the previous API versions, they are required starting with API 6.0 to fully support the regulations brought by PSD2 and SCA.

We always recommend using the latest version of the API in order to benefit from the latest functionalities and best performance. 

Availability

Available for all 2Checkout accounts.

Requirements

In order to be able to place orders with credit/debit cards via API, merchants fall under the requirements of the Payment Card Industry' Security Standard Council and are required to provide proof of attestation for an SAQ-D questionnaire before activation of this feature.   

If you want to use the 2Checkout API, please contact 2Checkout for activation.

Payment method object structure

Field name Type Required/Optional Description

CardNumber 

String

Required

 The number of credit/debit card.

CardType 

String

Optional

Can be: Visa, Visa electron, Mastercard, Maestro, Amex, Discover, Dankort, Carte bancaire, JCB, Hypercard, Elo card.

ExpirationYear 

String

Required

Card expiration year.

ExpirationMonth 

String

Required

Card expiration month.

CCID 

String

Required

The CVV/card security code.

HolderName 

String

Required

Card holder name.

Vendor3DSReturnURL 

String

Required

URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.

Vendor3DSCancelURL 

String

Required

URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.

RecurringEnabled

Boolean

Optional

true or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.

Request example

The full JSON used to place an order with credit cards would look like:

{
  "Items": [
    {
      "Code": "5DCB30C6B0",
      "Quantity": 1
    }
  ],
  "BillingDetails": {
    "Email": "example@email.com",
    "FirstName": "Customer First Name",
    "LastName": "Customer Last Name",
    "CountryCode": "US",
    "State": "California",
    "City": "San Francisco",
    "Address1": "Example Street",
    "Zip": "90210"
  },
  "PaymentDetails": {
    "Type": "CC",
    "Currency": "USD",
    "CustomerIP": "10.10.10.10",
    "PaymentMethod": {
      "CardNumber": "4111111111111111",
      "CardType": "VISA",
      "ExpirationYear": "2023",
      "ExpirationMonth": "12",
      "HolderName": "Red Doe",
      "CCID": "123",
      "Vendor3DSReturnURL": "http://yoursuccessurl.com",
      "Vendor3DSCancelURL": "http://yourcancelurl.com"
    }
  },
  "Language": "en",
  "Country": "US",
  "CustomerIP": "10.10.10.10",
  "Source": "Website",
  "ExternalCustomerReference": "externalCustomerId",
  "Currency": "USD",
  "MachineId": "123456789"
}

The API will respond with the full order object (for orders placed successfully) or with an error message.

3D Secure flow

More information on the 3DS and PSD2 information can be found on our blog.

With the roll-out of Strong Customer Authentication regulation in Europe, the use of 3D Secure becomes mandatory.  

Additional parameters are required in order to support the 3D Secure flow and this works by redirecting customers to pages provided by their banks, where they need to enter additional security tokens or passwords to trigger the completion of the charge. By using 3D Secure, you get additional protection from liability for fraudulent card payments, with shoppers having to go through an extra layer of authentication.

Diagram #1 3ds flow.png

These are the required steps for the 3DS flow:

1. The shopper fills in the payment details and places an order.

2. The merchant processes the order.

The merchant receives the shopper's data from the checkout page and triggers an order to 2Checkout with their information, including credit card data: cardholder name, credit card number, expiration date, and CVV are the mandatory fields.

Additionally, the merchant needs to provide two mandatory parameters in the PaymentMethod object: 

  • Vendor3DSReturnURL: the URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
  • Vendor3DSCancelURL: the URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.

3. 2Checkout processes the order from the merchant. The 2Checkout API will respond to the placeOrder API call with the order information or an error message.

4. The merchant processes the 2Checkout response.

Since 3DS is not always mandatory, how do we know when we are not on the 3DS flow?

If the order in the response is in Status AUTHRECEIVED or COMPLETE and PaymentDetails node looks like this, then the order does not require 3DS authorization.

{
  "Type": "CC",
  "Currency": "usd",
  "PaymentMethod": {
    "FirstDigits": "4111",
    "LastDigits": "1111",
    "CardType": "visa",
    "RecurringEnabled": false,
    "Vendor3DSReturnURL": null,
    "Vendor3DSCancelURL": null,
    "InstallmentsNumber": null
  },
  "CustomerIP": "10.11.12.1"
}

After this response, the shopper is redirected to the Finish page.

If the order in the response is in Status PENDING and the PaymentDetails node contains the Authorize3DS node, it'll look like this:

{
  "Type": "CC",
  "Currency": "usd",
  "PaymentMethod": {
    "Authorize3DS": {
      "Href": "http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize",
      "Method": "GET",
      "Params": {
        "avng8apitoken": "50dcb997be8b70bd"
      }
    },
    "Vendor3DSReturnURL": "http://shopping.cart.local/checkout/external/return/cc",
    "Vendor3DSCancelURL": "http://shopping.cart.local/checkout/external/cancel/cc",
    "FirstDigits": "4111",
    "LastDigits": "1111",
    "CardType": "Visa",
    "RecurringEnabled": false
  },
  "CustomerIP": "10.11.12.1"

5. The merchant redirects the shopper to the 3DS page.

The actual authorization is not done yet, but it will be completed after redirecting the shopper to the Authorize3DS URL where they enter the 3DS code. 

Example of URL (composed from Authorize3DS['href'] and Authorize3DS['Params']):

http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize?avng8apitoken=50dcb997be8b70bd

6. The shopper authenticates the payment.

The shopper reaches the bank's 3D Secure page, where they must complete the authentication flow by use of a one-time password (OTP) sent to their mobile phones by the issuing bank, or by use of a personal PIN.

7. The issuing bank processes the authentication request.

Based on the status of the authentication flow, the shopper is redirected back to the merchant's site, to the URL for either the success (Vendor3DSReturnURL) or the failed flow (Vendor3DSCancelURL). 

8. The merchant handles the 3DS flow result.

The shopper is redirected to the appropriate page, where the merchant needs to handle that specific case.

Integration test cases

Using the test credit cards available here, follow the next steps:

  1. Build a request in order to place a new order, with all the relevant information. Make sure that when the order is sent in the API, the response contains an order object (order was placed successfully).
  2. Handle the 3DS flows, both when 3DS is mandatory (and the shopper needs to be redirected to authorize the transaction), as well as where this is not needed (order is created with status AUTHRECEIVED or COMPLETE).
  3. If you have any additional webhook integrations, make sure that the webhooks are correctly configured and that the notifications are received and processed successfully. 

 

  • Was this article helpful?