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

 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.