Payment flow with credit cards with installments

The following payment methods are supported for the payment flow with credit cards with installments: local cards with installments for Turkey (Bonus, World, CardFinans, BankAsya, Paraf, Maximum, Axess) & Brazil (Elo card, Hipercard).

Availability

Available for all 2Checkout accounts.

Requirements

The functionality for orders with installments needs to be enabled for your 2Checkout account. Contact 2Checkout for activation.

How payments with installments work

Installments are available for Brazilian and Turkish shoppers with local Visa, MasterCard, or AMEX cards for non-recurring transactions.

The minimum installment threshold is 5 BRL/TRY. The maximum number of installments is 6.

Mandatory information for payments also includes a shopper's phone number and Fiscal Code (CPF/CNPJ).

To validate the number of installments, before placing the order, an API call must be made to getInstallments (on SOAP and JSON-RPC) or GET/orders/0/installments/ (on REST).

The getInstallments method receives as input the same input as the placeOrder method, and will return the number of installments and their value:

{
  "0": {
    "Amount": "384.45",
    "Currency": "BRL",
    "Number": "1"
  },
  "1": {
    "Amount": "192.23",
    "Currency": "BRL",
    "Number": "2"
  },
  "2": {
    "Amount": "128.15",
    "Currency": "BRL",
    "Number": "3"
  },
  "3": {
    "Amount": "96.11",
    "Currency": "BRL",
    "Number": "4"
  },
  "4": {
    "Amount": "76.89",
    "Currency": "BRL",
    "Number": "5"
  },
  "5": {
    "Amount": "64.08",
    "Currency": "BRL",
    "Number": "6"
  }
}

Payment method object structure

Parameter	Type / Description
PhoneNumber	Required (string) Shopper phone number.
FiscalCode	Required (string) For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).
CardNumber	Required (string) The card number.
CardType	Optional (string) Can be Visa, Visa electron, Mastercard, Maestro, Amex, Discover, Dankort, Carte Bancaire, JCB, Hipercard, Elo card
ExpirationYear	Required (string) Card expiration year.
ExpirationMonth	Required (string) Card expiration month.
CCID	Required (string) The CVV/card security code.
HolderName	Required (string) Card holder name.
InstallmentsNumber	Optional (int) Number of installments. Available only when customers in Brazil or Turkey pay with Visa or MasterCard using Brazilian Real or Turkish Lira as the order currency. Use 1 or exclude the parameter for full payments.
Vendor3DSReturnURL	Required (string) URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
Vendor3DSCancelURL	Required (string) URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
RecurringEnabled	Optional (boolean) True or false, depending on whether the shoppers checked the subscription auto-renewal checkbox or not, during the purchase process.

Request sample

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

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

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

Notes on orders with installments

• The 2Checkout payout for the full order value, regardless of the number of installments (this is covered directly by the banks).

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.