Skip to main content
knowledgecenter.2checkout.com

Payment flow with Credit Cards with Installments

Overview

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. Please 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 phone number and Fiscal Code (CPF/CNPJ).

In order 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 an 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

Field name Type Required/Optional Description

Phone Number

String

Required

Shopper phone number.

Fiscal Code

String

Required

For Brazilian customers it represents the Fiscal Code (CPF/CNPJ).

CardNumber 

String

Required

The card number.

CardType 

String

Optional

Can be Visa, Visa electron, Mastercard, Maestro, Amex, Discover, Dankort, Carte Bancaire, JCB, Hipercard, 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.

InstallmentsNumber

Int

Optional

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 

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": "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. 

 

  • Was this article helpful?