Installment transactions are available for the following transactions:
Debit transaction including all installments
PA transaction including all installments + CP
Debit transaction including all installments
Channels (entityId) for installments
For the purposes of processing installments transactions, a dedicated channel (entity ID) will be created, per country. The number of installments is determined in the payment request, which is explained in further detail in the “Implementation” section below.
For example:
Brazil
Mexico
Calculation of installments
From a technical perspective, a transaction in installments is one single transaction. The issuing bank handles the charges to the customer, which will occur each month.
The calculation of the installments amount for each month is done by dividing the amount by the number of installments. The resulting value is then added up with a precision of two decimals. In case the result is lower than the amount, the missing fraction is added to the first installment.
Brazil
Example:
Transaction of 100.00 BRL in 3 installments:
100.00 BRL/ 3 = 33,33 BRL
33,33 BRL x 3 = 99,99 BRL
First installment: BRL 33,34
2nd and 3rd installments: BRL 33,33
Mexico
Example:
Transaction of 300.00 MXN in 3 installments:
300.00 BRL/ 3 = 100.00 MXN
First installment: 100.00 MXN
2nd and 3rd installments: 100.00 MXN
Limitations
From a technical perspective, up to 12 installments are allowed. Please check back with the Project Owner the maximum number of installments agreed in your contract.
Minimum amount for an installment
Brazil
The minimum amount for an installment is 5.00 BRL. Ex: Total DB amount 10.00 BRL in 2 installments (5.00 BRL/installment).
Mexico
The minimum total Amount for 3, 6, 9 and 12 installments are:
300.00 MXN / 3 installments
1000.00 MXN / 3 installments
2000.00 MXN / 3 installments
600.00 MXN / 6 installments
1000.00 MXN / 6 installments
2000.00 MXN / 6 installments
900.00 MXN / 9 installments
1000.00 MXN / 9 installments
2000.00 MXN / 9 installments
1200.00 MXN / 12 installments
2000.00 MXN / 12 installments
3000.00 MXN / 12 installments
Note: 2, 4, 5, 7, 8, 10 and 11 installments are not supported in Mexico! You should obligatory send exactly 3, 6, 9 or 12 installments in according to the minimum amount above.
Implementation
Installments transactions have a single parameter added to a “normal” transaction: recurring.numberOfInstallments
.
PPRO supports two flows for processing Credit and Debit Card transactions, either Debit (DB) Flow or Preauthorization (PA) and Capture (CP) flow. Both flows are valid; please discuss both options with your Account Manager.
Debit (DB) flow authorizes and debits card holder’s account in a single step.
Preauthorization (PA) and Capture (CP) flow splits authorizes and debiting card holder’s account into two steps.
Note: In Mexico installments are not available for Amex PA (Preauthorization)!
Note: For recurring transactions the CVV is not mandatory!
Test Cards
Brazil
Mexico
COPYandPAY - Installments
Debit (DB)
Installments COPYandPAY Debit (DB) Request Response
Copy curl https://test.oppwa.com/v1/checkouts \
-d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
-d "amount=100.00" \
-d "currency=BRL" \
-d "paymentType=DB" \
-d "merchantTransactionId=Order Number 123" \
-d "customer.merchantCustomerId=12345678909" \
-d "customer.givenName=Jose" \
-d "customer.surname=da Silva" \
-d "customer.email= info@provider.com" \
-d "customer.ip=123.123.123.123" \
-d "descriptor=123 Usage" \
-d "billing.city=Sao Paulo" \
-d "billing.country=BR" \
-d "billing.state=SP" \
-d "billing.street1=Rua Itapeva 547" \
-d "billing.postcode=01332000" \
-d "customParameters[product]=1 month membership" \
-d "customParameters[merchant_website]=www.store.com" \
-d "recurring.numberOfInstallments=3" \
-d "recurringType=INITIAL" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
Copy {
"result":{
"code":"000.200.100",
"description":"successfully created checkout"
},
"buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
"timestamp":"2019-05-07 15:36:03+0000",
"ndc":"6B2F955A6E4EB97C8C3FB1108B13484A.uat01-vm-tx04",
"id":"6B2F955A6E4EB97C8C3FB1108B13484A.uat01-vm-tx04"
}
To create the payment form you just need to add the following lines of HTML/Javascript to your page and populating the following variables • The checkout id that you got in the response from step 1
Copy <script src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
The shopperresultUrl
, is the page on your site where the customer should be redirected to after the payment is processed and the brands that will be available
Copy <form action="{shopperResultUrl}" class="paymentWidgets"> VISA MASTER AMEX DINERS DISCOVER ELO JCB</form>
After you input the credit card data on the form above, the request for payment is processed.
PreAuthorization (PA) + Capture (CP)
Installments COPYandPAY PreAuthorization (PA) Request Response
Copy curl https://test.oppwa.com/v1/checkouts \
-d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
-d "amount=100.00" \
-d "currency=BRL" \
-d "paymentType=PA" \
-d "merchantTransactionId=Order Number 123" \
-d "customer.merchantCustomerId=12345678909" \
-d "customer.givenName=Jose" \
-d "customer.surname=da Silva" \
-d "customer.email= info@provider.com" \
-d "customer.ip=123.123.123.123" \
-d "descriptor=123 Usage" \
-d "billing.city=Sao Paulo" \
-d "billing.country=BR" \
-d "billing.state=SP" \
-d "billing.street1=Rua Itapeva 547" \
-d "billing.postcode=01332000" \
-d "customParameters[product]=1 month membership" \
-d "customParameters[merchant_website]=www.store.com" \
-d "recurring.numberOfInstallments=3" \
-d "recurringType=INITIAL" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
Copy {
"result":{
"code":"000.200.100",
"description":"successfully created checkout"
},
"buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
"timestamp":"2019-05-07 15:46:30+0000",
"ndc":"9407F5C5F945F4FC47C67B8DD4542E1F.uat01-vm-tx02",
"id":"9407F5C5F945F4FC47C67B8DD4542E1F.uat01-vm-tx02"
}
To create the payment form you just need to add the following lines of HTML/Javascript to your page and populating the following variables • The checkout id that you got in the response from step 1
Copy <script src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
The shopperresultUrl
, is the page on your site where the customer should be redirected to after the payment is processed and the brands that will be available
Copy <form action="{shopperResultUrl}" class="paymentWidgets"> VISA MASTER AMEX DINERS DISCOVER ELO JCB</form>
Get the payment status - Preauthorization (PA)
Request Response
Copy curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
-d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
-H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
Copy {
"id":"8ac7a4a26a8f88ad016a931aaa893b0d",
"paymentType":"PA",
"paymentBrand":"VISA",
"amount":"100.00",
"currency":"BRL",
"descriptor":"123 Usage",
"merchantTransactionId":"Order Number 123",
"recurringType":"INITIAL",
"result":{
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'"
},
"card":{
"bin":"411111",
"last4Digits":"1111",
"holder":"Integration test",
"expiryMonth":"10",
"expiryYear":"2019"
},
"customer":{
"givenName":"Jose",
"surname":"da Silva",
"merchantCustomerId":"12345678909",
"email":"info@provider.com",
"ip":"123.123.123.123"
},
"billing":{
"street1":"Rua Itapeva 547",
"city":"Sao Paulo",
"state":"SP",
"postcode":"01332000",
"country":"BR"
},
"customParameters":{
"SHOPPER_EndToEndIdentity":"35b4d1421d09b7eb9fdf753fefd30bf80d033c6842b8b45633bfb9e68137ebbf",
"product":"1 month membership",
"CTPE_DESCRIPTOR_TEMPLATE":"${USAGE}",
"merchant_website":"www.store.com"
},
"risk":{
"score":"0"
},
"buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
"timestamp":"2019-05-07 16:22:40+0000",
"ndc":"694725F6D8760E88260091ACB963E33C.uat01-vm-tx04",
"recurring":{
"numberOfInstallments":3
}
}
Capture the payment:
CP (Capture) Request Response
Copy curl https://test.oppwa.com/v1/payments/{id} \
-d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
-d "amount=100.00" \
-d "currency=BRL" \
-d "paymentType=CP" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
Copy {
"id":"8ac7a4a06a8f68dd016a931e64f53696",
"referencedId":"8ac7a4a26a8f88ad016a931aaa893b0d",
"paymentType":"CP",
"amount":"100.00",
"currency":"BRL",
"descriptor":"123 Usage",
"merchantTransactionId":"Order Number 123",
"result":{
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'"
},
"resultDetails":{
"ConnectorTxID1":"8ac7a4a06a8f68dd016a931e64f53696",
"connectorInstanceId":"10.2.3.93",
"acquirerReturnCode":"6",
"ExtendedDescription":"Transaction succeeded",
"acquirerTxId3":"8ac7a4a26a8f88ad016a931aaa893b0d",
"merchantAccount":"Cielo_ACON3_STAGING",
"connectorVersion":"3.2.13",
"AcquirerResponse":"000.000.000",
"acquirerParentTxId":"400e6474-9f1c-47b0-9031-d1633029ff72",
"connectorName":"Cielo",
"acquirerInitialTxId":"400e6474-9f1c-47b0-9031-d1633029ff72",
"acquirerReturnMessage":"Operation Successful",
"acquirerTxId1":"400e6474-9f1c-47b0-9031-d1633029ff72",
"acquirerTxId2":"0507012240529#APG@089234"
},
"customer":{
"merchantCustomerId":"12345678909"
},
"buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
"timestamp":"2019-05-07 16:26:44+0000",
"ndc":"8a8294174e918ca6014e9c6f5ae12a9c_f0cd5781fa5b4434babfd53456d98314"
}
Server-to-Server - Installments
Debit (DB)
Installments Server-to-Server Debit (DB) Request Response
Copy curl https://test.oppwa.com/v1/payments \
-d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
-d "amount=15.00" \
-d "currency=BRL" \
-d "paymentType=DB" \
-d "paymentBrand=VISA" \
-d "card.number=4111111111111111" \
-d "card.holder=Jose da Silva" \
-d "card.expiryMonth=05" \
-d "card.expiryYear=2020" \
-d "card.cvv=123" \
-d "merchantTransactionId=Order Number 123" \
-d "customer.merchantCustomerId=12345678909" \
-d "customer.givenName=Jose" \
-d "customer.surname=da Silva" \
-d "customer.email= info@provider.com" \
-d "customer.ip=123.123.123.123" \
-d "descriptor=123 Usage" \
-d "billing.city=Sao Paulo" \
-d "billing.country=BR" \
-d "billing.state=SP" \
-d "billing.street1=Rua Itapeva 547" \
-d "billing.postcode=01332000" \
-d "customParameters[product]=1 month membership" \
-d "customParameters[merchant_website]=www.store.com" \
-d "recurring.numberOfInstallments=3" \
-d "recurringType=INITIAL" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
Copy {
"id":"8a82944a64f528ad0165013c47ab70e7",
"paymentType":"DB",
"paymentBrand":"VISA",
"amount":"15.00",
"currency":"BRL",
"descriptor":"123 Usage",
"merchantTransactionId":"Order Number 123",
"result":{
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'"
},
"card":{
"bin":"411111",
"last4Digits":"1111",
"holder":"Jose da Silva",
"expiryMonth":"05",
"expiryYear":"2020"
},
"customer":{
"givenName":"Jose",
"surname":"da Silva",
"merchantCustomerId":"12345678909",
"email":" info@provider.com ",
"ip":"123.123.123.123"
},
"billing":{
"street1":"Rua Itapeva 547",
"city":"Sao Paulo",
"state":"SP",
"postcode":"01332000",
"country":"BR"
},
"customParameters":{
"merchant_website":"www.store.com",
"product":"1 month membership"
},
"risk":{
"score":"100"
},
"buildNumber":"e7a0be7d2001c256dba942c51da40ff290899d79@2018-07-31 11:16:15 +0000",
"timestamp":"2018-08-03 19:20:53+0000",
"ndc":"8a8294174e918ca6014e9c6f5ae12a9c_defc7dda58e14b89b96002795a2ead62",
"recurring":{
"numberOfInstallments":3
}
}
PreAuthorization (PA) + Capture)
Installments Server-to-Server PreAuthorization (PA) Request Response Example Capture (CP) Request Response
Copy curl https://test.oppwa.com/v1/payments \
-d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
-d "amount=300.00" \
-d "currency=BRL" \
-d "paymentType=PA" \
-d "paymentBrand=VISA" \
-d "card.number=4111111111111111" \
-d "card.holder=Jose da Silva" \
-d "card.expiryMonth=05" \
-d "card.expiryYear=2020" \
-d "card.cvv=123" \
-d "merchantTransactionId=Order Number 123" \
-d "customer.merchantCustomerId=12345678909" \
-d "customer.givenName=Jose" \
-d "customer.surname=da Silva" \
-d "customer.email= info@provider.com" \
-d "customer.ip=123.123.123.123" \
-d "descriptor=123 Usage" \
-d "billing.city=Sao Paulo" \
-d "billing.country=BR" \
-d "billing.state=SP" \
-d "billing.street1=Rua Itapeva 547" \
-d "billing.postcode=01332000" \
-d "customParameters[product]=1 month membership" \
-d "customParameters[merchant_website]=www.store.com" \
-d "recurring.numberOfInstallments=3" \
-d "recurringType=INITIAL" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
Copy {
"id":"8a82944964f4e0a701650146063971ce",
"paymentType":"PA",
"paymentBrand":"VISA",
"amount":"300.00",
"currency":"BRL",
"descriptor":"123 Usage",
"merchantTransactionId":"Order Number 123",
"result":{
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'"
},
"card":{
"bin":"411111",
"last4Digits":"1111",
"holder":"Jose da Silva",
"expiryMonth":"05",
"expiryYear":"2020"
},
"customer":{
"givenName":"Jose",
"surname":"da Silva",
"merchantCustomerId":"12345678909",
"email":" info@provider.com ",
"ip":"123.123.123.123"
},
"billing":{
"street1":"Rua Itapeva 547",
"city":"Sao Paulo",
"state":"SP",
"postcode":"01332000",
"country":"BR"
},
"customParameters":{
"merchant_website":"www.store.com",
"product":"1 month membership"
},
"risk":{
"score":"100"
},
"buildNumber":"e7a0be7d2001c256dba942c51da40ff290899d79@2018-07-31 11:16:15 +0000",
"timestamp":"2018-08-03 19:31:32+0000",
"ndc":"8a8294174e918ca6014e9c6f5ae12a9c_263b494adcfe4e16bb56753de4367cf8",
"recurring":{
"numberOfInstallments":3
}
}
Copy curl https://test.oppwa.com/v1/payments/{id} \
-d "entityId=8a8294174e918ca6014e9c6f5ae12a9c" \
-d "amount=300.00" \
-d "currency=BRL" \
-d "paymentType=CP" \
-d "testMode=EXTERNAL" \
-H "Authorization: Bearer OGE4Mjk0MTcyODFiOGVlMzAxMjgyOTkwNjZmNTBjZGJ8ZGVtbw=="
Copy {
"id":"8a82944964f4e0a7016501476ad2747e",
"referencedId":"8a82944964f4e0a701650146063971ce",
"paymentType":"CP",
"paymentBrand":"VISA",
"amount":"15.00",
"currency":"BRL",
"descriptor":"123 Usage",
"merchantTransactionId":"Order Number 123",
"result":{
"code":"000.100.112",
"description":"Request successfully processed in 'Merchant in Connector Test Mode'"
}, "card":{
"bin":"411111",
"last4Digits":"1111",
"holder":"Jose da Silva",
"expiryMonth":"05",
"expiryYear":"2020"
},
"customer":{
"givenName":"Jose",
"surname":"da Silva",
"merchantCustomerId":"12345678909",
"email":"info@provider.com",
"ip":"123.123.123.123"
},
"billing":{
"street1":"Rua Itapeva 547",
"city":"Sao Paulo",
"state":"SP",
"postcode":"01332000",
"country":"BR"
},
"buildNumber":"33ee72b29c129ddd5a37c156e074f45020691f79@2019-05-03 03:42:17 +0000",
"timestamp":"2018-08-03 19:33:03+0000",
"ndc":"8a8294174e918ca6014e9c6f5ae12a9c_b7ec3dae6b1e40f58f95fe8709c9a069"
}