You can use CellPoint Velocity's Installments feature to allow customers to make payments in installments. This feature is applicable to an API integration for credit card transactions where the cardholder's country is the same as the pricing country. You can use the Vision platform to configure the card types and customers for whom this feature is available and to set the maximum number of months a customer may select.

Workflow

Initialize request - The customer clicks the payment button, prompting the merchant's front-end application to send an Initialize request to the Velocity API.
Initialize response - The API checks available payment options. It sends an Initialize response to the merchant that includes information on whether each card is eligible for installment payments.
Card selection - The front-end application displays payment options to the customer. The customer enters their card number or selects a stored card, and the front-end application checks the Initialize response to determine whether that card is eligible for installments.
Get Installment Plans request - If the selected card is eligible for installments, the front-end application sends a Get Installment Plans request to the API to get the available installment options.
Get Installment Plans response - The API checks the card's eligibility and returns a list containing the number of installments in which the customer may pay.
Installments selection - The front-end application displays the available installment options to the customer, and the customer selects the number of installments in which they want to pay.
Finish session - The merchant includes the customer's selection in an Authorize API request. The transaction proceeds as normal, and CellPoint Digital charges the selected card the installment amount each month, as the merchant has specified through the Vision platform.

Prerequisite

Work with your CellPoint Digital sales representative or account manager to sign up, set up your test account, and access your testing credentials, and to sign up for and set up the Installments feature.

Integration

Complete the following steps to use the Installments feature with your integration.

1. Initialize payment

Endpoint: /mpoint/initialize-payment
Method: POST

Once the page has loaded, send a POST request to the /mpoint/initialize-payment endpoint of the CellPoint Velocity API. For more information, see our Initialize Payment API reference.

Below is sample code of an Initialize request:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <initialize-payment account="101131" client-id="10101">
        <transaction order-no="TES442" type-id="1">
            <amount currency-id="170" country-id="405">29000000</amount>
            <hmac>d21ecb779a24763e3c99999999999999999e3ed619da965f025ed89fbdb621278476d1f8d7f7e0c203c95b474e3a30ebec2fd4972bd0c62230cba141e230286b</hmac>
            <orders/>
            <fees>
                <fee>2300</fee>
            </fees>
            <additional-data/>
        </transaction>
        <client-info language="en" sdk-version="2.0.0" version="2.0.0" platform="HTML5" profileid="">
            <mobile operator-id="40500" country-id="405">7676565454</mobile>
            <email>[email protected]</email>
            <customer-ref>[email protected]</customer-ref>
            <device-id>2E8667F78B23402BBFFFFFFFFFFF58D314566333</device-id>
            <ip>62.242.147.103</ip>
        </client-info>
    </initialize-payment>
</root>

The API sends an Initialize response like the sample code below.

Note the following:

max-installments - If any available payment option is eligible for installments, the response will contain the <installment> element with the attribute max-installments = "1". If no payment option is eligible for installments, max-installments = "0".
installment - The <card> element for each payment method contains the installment attribute. If the value of installment is 1, that payment method is eligible for installments; if it is 0, the payment method is not eligible.
transaction ID - Take the transaction ID returned in the Initialize response and use it in your Get Installment Plans request. In the Initialize response, this is the value of the <transaction> element's attribute id . In the Get Installment Plans request, it is the text content of <id>, a child of <transaction>.

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <client-config account="101131" auto-capture="false" enable-cvv="true" id="10101" max-stored-cards="-1" mode="1" store-card="0">
        <installment frequency="0" max-installments="0" type="1" />
        <name>CPD Demo</name>
        <callback-url>[URL]</callback-url>
        <accept-url>[URL]</accept-url>
        <cancel-url>[URL]</cancel-url>
    </client-config>
    <transaction auto-capture="false" eua-id="-1" id="80687091" language="en" mode="1" order-no="TES442" type-id="1">
        <amount alpha2code="CO" alpha3code="COL" code="170" country-id="405" currency="COP" currency-id="170" decimals="2" format="" symbol="$">29000000</amount>
        <orders/>
        <mobile country-id="405" operator-id="40500">7676565454</mobile>
        <email>[email protected]</email>
        <customer-ref>[email protected]</customer-ref>
        <callback-url>[URL]</callback-url>
        <accept-url>[URL]</accept-url>
        <cancel-url>[URL]</cancel-url>
    </transaction>
    <session id="1883424" total-amount="29000000" type="1">
        <amount alpha2code="CO" alpha3code="COL" code="170" country-id="405" currency="COP" currency-id="170" format="" symbol="$">29000000</amount>
        <status>4001</status>
    </session>
    <cards>
        <card cvc-length="3" cvcmandatory="false" dcc="true" enabled="true" id="8" installment="0" max-length="16" min-length="13" payment-type="1" preferred="false" presentment-currency="false" processor-type="1" psp-id="-1" state-id="1" type-id="8">
            <name>VISA</name>
            <prefixes>
                <prefix id="414">
                    <min>4</min>
                    <max>4</max>
                </prefix>
            </prefixes>VISA
        </card>
        <card cvc-length="3" cvcmandatory="false" dcc="true" enabled="true" id="7" installment="0" max-length="16" min-length="16" payment-type="1" preferred="false" presentment-currency="false" processor-type="1" psp-id="-1" state-id="1" type-id="7">
            <name>Master Card</name>
            <prefixes>
                <prefix id="412">
                    <min>2221</min>
                    <max>2720</max>
                </prefix>
                <prefix id="413">
                    <min>51</min>
                    <max>55</max>
                </prefix>
                <prefix id="1676">
                    <min>518834</min>
                    <max>518839</max>
                </prefix>
            </prefixes>Master Card
        </card>
    </cards>
	<stored-cards>
		<card cvc-length="3" cvcmandatory="false" dcc="true" id="8" installment="1" preferred="true" psp-id="2" type-id="1">
			<name>myVisa</name>
			<card-number-mask>4711 10** **** 0000</card-number-mask>
			<expiry>06/29</expiry>
		</card>
	</stored-cards>
    <wallets />
    <apms />
    <aggregators>
        <card cvc-length="0" cvcmandatory="false" dcc="false" enabled="true" id="97" installment="0" max-length="0" min-length="0" payment-type="7" preferred="false" presentment-currency="false" processor-type="7" psp-id="-1" state-id="1" type-id="97">
            <name>PSE</name>
            <prefixes />
            <active-payment-methods>
                <payment-method>
                    <logoName>313ba99e-ec60-4671-a18e-195b508002f4</logoName>
                    <logoURL>0</logoURL>
                    <displayName>A continuación seleccione su banco</displayName>
                    <issuingBank>0</issuingBank>
                    <displayOrder>1</displayOrder>
                </payment-method>
                <payment-method>
                    <logoName>4cd574a8-849c-429c-bcab-429a5d4a0d1e</logoName>
                    <logoURL>1815</logoURL>
                    <displayName>ALIANZA FIDUCIARIA</displayName>
                    <issuingBank>1815</issuingBank>
                    <displayOrder>2</displayOrder>
                </payment-method>
            </active-payment-methods>PSE
        </card>
    </aggregators>
</root>

For a description of response parameters, see Initialize Payment.

2. Check selected payment method

Take the available payment options listed in the Initialize response and display them to the customer. When the customer enters their card number or selects a stored card, check the Initialize response to determine whether that card is eligible for installments.

If the card is eligible, proceed to step 3. If it is not eligible, send an Authorize request as normal; see Authorize Payment for more information.

❗️
If you have signed up for the Installments feature, you may need to include the installment object in all Authorize requests, regardless of whether an installment plan is available or selected. Check with your CellPoint Digital sales representative or account manager to determine if this is the case.

3. Get available installment plans

Endpoint: /crs/routingservice/get-installment-plans
Method: GET

Send a Get Installment Plans request to get a list of installment plans available to the customer for their selected payment card. For API reference information, see get-installment-plans.

Include the following in this request:

In transaction, include id with the transaction ID found in the Initialize response.
In transaction: card, include issuer-identification-number with the first 11 digits of the selected payment card's number.

See the sample code for a Get Installment Plans request below:

<?xml version="1.0" encoding="UTF-8"?>
<installment_plans_search_criteria>
    <transaction>
        <id>80306591</id>
        <amount>
            <value>290000</value>
            <country_id>405</country_id>
            <currency_id>170</currency_id>
        </amount>
        <card>
            <id>7</id>
            <type_id>7</type_id>
            <amount>
                <value>290000</value>
                <country_id>405</country_id>
                <currency_id>170</currency_id>
            </amount>
            <issuer_identification_number>53037104094</issuer_identification_number>
        </card>
    </transaction>
    <client_info>
        <platform>HTML5</platform>
        <language>en</language>
        <version>2.0.0</version>
        <mobile>
            <mobile>7676565454</mobile>
            <country_id>405</country_id>
            <mobile_type>MobileEnriched</mobile_type>
            <validated>true</validated>
        </mobile>
        <email>
            <email>[email protected]</email>
            <email_type>EmailEnriched</email_type>
            <validated>true</validated>
        </email>
        <client_id>10101</client_id>
    </client_info>
</installment_plans_search_criteria>

If the card is eligible for installments, the API returns a list of available installment plans in the Get Installment Plans response. In the list, each installment_plan element contains a distinct integer; this value represents the number of months across which the customer may spread their installment payments. For example, if the value of installment plan is 6, the customer may choose to pay in 6 monthly installments.

Below is a sample Get Installment Plans response with available installment plans:

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<installment_plans_search_response>
		<installment_plans>
			<installment_plan>1</installment_plan>
			<installment_plan>2</installment_plan>
			<installment_plan>3</installment_plan>
			<installment_plan>4</installment_plan>
			<installment_plan>5</installment_plan>
			<installment_plan>6</installment_plan>
			<installment_plan>7</installment_plan>
			<installment_plan>8</installment_plan>
			<installment_plan>9</installment_plan>
			<installment_plan>10</installment_plan>
			<installment_plan>11</installment_plan>
			<installment_plan>12</installment_plan>
			<installment_plan>13</installment_plan>
			<installment_plan>14</installment_plan>
			<installment_plan>15</installment_plan>
			<installment_plan>16</installment_plan>
			<installment_plan>17</installment_plan>
			<installment_plan>18</installment_plan>
			<installment_plan>19</installment_plan>
			<installment_plan>20</installment_plan>
			<installment_plan>21</installment_plan>
			<installment_plan>22</installment_plan>
			<installment_plan>23</installment_plan>
			<installment_plan>24</installment_plan>
			<installment_plan>25</installment_plan>
			<installment_plan>26</installment_plan>
			<installment_plan>27</installment_plan>
			<installment_plan>28</installment_plan>
			<installment_plan>29</installment_plan>
			<installment_plan>30</installment_plan>
			<installment_plan>31</installment_plan>
			<installment_plan>32</installment_plan>
			<installment_plan>33</installment_plan>
			<installment_plan>34</installment_plan>
			<installment_plan>35</installment_plan>
			<installment_plan>36</installment_plan>
		</installment_plans>
	</installment_plans_search_response>
</root>

If no installment plans are available, the API returns an empty response like the example below. (This may happen if no business rules are configured or matched for the specific transaction.)

<?xml version="1.0" encoding="UTF-8"?>
<root>
	<installment_plans_search_response>
		<installment_plans/>
	</installment_plans_search_response>
</root>

4. Get customer's selection

Using the contents of the Get Installment Plans response, show the list of possible numbers of installments to the customer. Let them select the number of installments in which they will pay. For example, if they select 6, they will divide the total payment between 6 monthly payments.

CellPoint Digital recommends displaying these options in a drop-down menu, like in the images below:

5. Request authorization

Endpoint: /mpoint/authorize-payment
Method: POST

Construct and send an Authorize request. In the request's transaction element, include the installment object with the child element value, whose text content is the number of installments in which the customer has chosen to pay.

Below is an example of an Authorize request for a payment using installments:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <authorize-payment account="101131" client-id="10101">
        <transaction type-id="10091" id="80187037" store-card="false">
            <card type-id="7">
                <amount country-id="405" currency-id="170">29000000</amount>
                <cvc>123</cvc>
                <card-holder-name>CPD Demo</card-holder-name>
                <card-number>5305305309428777</card-number>
                <expiry>10/29</expiry>
                <address country-id="405">
                    <first-name>First</first-name>
                    <last-name>Last</last-name>
                    <street>123 Test St.</street>
                    <postal-code>711111</postal-code>
                    <city>Test City</city>
                    <state>Test State</state>
                    <contact-details>
                        <mobile operator-id="64000" country-id="405">9898989898</mobile>
                        <email>[email protected]</email>
                    </contact-details>
                </address>
            </card>
            <installment>
                <value>5</value>
            </installment>
            <hmac>d21ecb779a24763e3c99999999999999999e3ed619da965f025ed89fbdb621278476d1f8d7f7e0c203c95b474e3a30ebec2fd4972bd0c62230cba141e230286b</hmac>
        </transaction>
        <client-info language="en" sdk-version="2.0.0" version="2.0.0" platform="HTML5" profileid="">
            <mobile operator-id="40500" country-id="405">7676565454</mobile>
            <email>[email protected]</email>
            <customer-ref>[email protected]</customer-ref>
            <device-id>2E8667F78B23402BBFFFFFFFFFFF58D314566333</device-id>
        </client-info>
    </authorize-payment>
</root>

The API returns an Authorize response indicating whether authorization has succeeded or failed. If it succeeds, the transaction proceeds as normal, and CellPoint Digital charges the selected card the installment amount each month, as you have specified through the Vision platform.