Overview
This page describes how to implement the Credit Card Installments feature using the addendums.localPayment
addendum, which allows your customer to pay in installments when using a credit card.
The maximum number of installments can be set according to your business requirement using a request to the Payment Page open URL or /payment
API request.
The merchant’s acquirer bank must support processing a payment using installments; otherwise, this feature is not available.
Supported Countries
Brazil, Mexico, Colombia, Chile, Peru, Israel
CC Installments in Payment Page (Cashier)
The merchant can control the implementation of payment installments and their presentation by sending the following parameters to the Payment Page open URL:
allow_installments=1
(whether to allow payment installments to be used)max_num_installments
Example of URL
https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=123456789&merchant_site_id=123456&user_token=auto&user_token_id=Test_&item_open_amount_1=true&item_min_amount_1=1&item_max_amount_1=100&item_name_1=Cashier%20Test%20product%201&item_amount_1=1.23&item_quantity_1=1&total_amount=1.23¤cy=MXN&version=4.0.0&first_name=test&last_name=test&address1=test&city=test&zip=123456&country=MX&phone1=123456&email=test@test.com&payment_method=cc_card&userid=test1234&allow_installments=1&max_num_installments=5&time_stamp=&checksum=27e904e276faf01f18f4a93ab389d4c7
Example of Installments in the Payment Page
CC Installments via REST API
To implement the Credit Card Installments feature, send a /payment
request with its mandatory parameters and include:
addendums.localPayment
block containing:
numberOfInstallments
– The total number of installments (including the first installment).
nationalId
– The user’s national ID number.
installmentType
– The type of installment.
Possible values:
1 – Deferred with interest
2 – Deferred without interest
3 – Deferred without interest and months of grace
debitType
– The type of debit.
Possible values:
1 – Singular payment
2 – Installments
3 – Special debit
Example /payment
Request
{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "userTokenId": "<unique customer identifier in merchant system>", "currency": "USD", "amount": "10.37", "paymentOption": { "card": { "cardNumber": "4444493318246892", "cardHolderName": "John Smith", "expirationMonth": "12", "expirationYear": "25", "CVV": "670" } }, "billingAddress": { "firstName": "John", "lastName": "Smith", "email": "john.smith@email.com", "country": "CL" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "addendums": { "localPayment": { "numberOfInstallments": "121", "nationalId": "123456789", "installmentType": "3", "debitType": "2" } }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }
Example /payment
Response
{ "reason":"", "orderId":"38606501", "customData":"Custom Data Inserted By Darin!", "merchantSiteId":"126006", "gwExtendedErrorCode":0, "merchantId":"2502136204546424962", "paymentOption":{ "userPaymentOptionId":"8414971", "card":{ "issuerBankName":"BANCO DE CHILE", "ccCardNumber":"4444493318246892", "bin":"548652", "avsCode":"S", "threeD":{ }, "cardType":"Credit", "ccExpMonth":"12", "ccExpYear":"25", "issuerCountry":"CL", "isPrepaid":"false", "acquirerId":"99", "cardBrand":"MASTERCARD", "cvv2Reply":"P", "last4Digits":"4763" } }, "externalTransactionId":"211008371893", "authCode":"416380", "transactionStatus":"APPROVED", "issuerDeclineCode":"", "clientRequestId":"D6F0GRT5D", "internalRequestId":24583551, "version":"1.0", "transactionId":"2110000000008371893", "transactionType":"Sale", "gwErrorCode":0, "externalSchemeTransactionId":"MCS00LNQW0120 ", "clientUniqueId":"695701003", "errCode":0, "sessionToken":"96fd6575-6533-4791-a106-c1bf2d82ad23", "userTokenId":"X874NSXD6VK0", "issuerDeclineReason":"", "fraudDetails":{ "score":"0", "finalDecision":"Accept" }, "status":"SUCCESS" }
Appendix – Colombia Fields
As part of the Nuvei integration for local transaction processing in Colombia, the merchants can add the following optional parameters under the addendums.localPayment
block in addition to the parameters listed in CC Installments via REST API:
vatAmount
– VAT tax calculated by the merchant in domestic currency.nationalConsumptionTaxAmount
– Consumption tax calculated by the merchant in domestic currency.taxAmountBase
– The purchase amount in domestic currency and the amount based on the taxes that were calculated.tipAmount
– Tip amount paid during the purchase transaction.taxCurrencyCodeBase
– ISO Alpha 3 currency code.airportChargeAmount
– The amount of the airport charge part when purchasing an airline ticket.
Example /payment
Request
{ "sessionToken": "<sessionToken from getSessionToken>", "merchantId": "<your merchantId>", "merchantSiteId": "<your merchantSiteId>", "clientRequestId": "<unique request ID in merchant system>", "clientUniqueId": "<unique transaction ID in merchant system>", "userTokenId": "<unique customer identifier in merchant system>", "currency": "USD", "amount": "10.37", "paymentOption": { "card": { "cardNumber": "4444493318246892", "cardHolderName": "John Smith", "expirationMonth": "12", "expirationYear": "25", "CVV": "670" } }, "billingAddress": { "firstName": "John", "lastName": "Smith", "email": "john.smith@email.com", "country": "CL" }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "addendums": { "localPayment": { "numberOfInstallments": "121", "vatAmount": "20", "nationalConsumptionTaxAmount": "19", "taxAmountBase": "18", "nationalId": "123456789", "tipAmount": "17", "taxCurrencyCodeBase": "USD", "airportChargeAmount": "15", "installmentType": "3", "debitType": "2" } }, "urlDetails": { "notificationUrl": "<URL to which DMNs are sent>" }, "timeStamp": "<YYYYMMDDHHmmss>", "checksum": "<calculated checksum>" }