Last Updated: 21 November 2024 | Change Log

Latin America installments

Request a one-time installment payment, to allow the customer's bank to collect subsequent payments automatically.

The request must contain:

customerAgreement.type = installment - used to indicate the customer has agreed the processing arrangement
customerAgreement.installmentType = latinAmerica - used to define the type of installments service
customerAgreement.installmentPlan.numberOfInstallments = 12 - used to indicate the number of installments that the requested amount should be broken into by the aquirer bank

If PSD2/SCA or other regional mandates apply also set:

threeDS.challenge.preference to mandated

Optionally you can store the card details:

customerAgreement.storedCardUsage = first
tokenCreation.type = worldpay - include if you're storing the card as a Worldpay token

Or use already stored card details:

customerAgreement.storedCardUsage = subsequent

Apple Pay & Google Pay are not yet supported when setting up an installment.

Important: You must have agreement from your customer to store their card details.

Collect the card details and send an API request with these details to the Payments resource.

Request

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "method": "card",
        "paymentInstrument": {
            "type": "plain",
            "cardNumber": "4000000000001091",
                "expiryDate": {
                "month": 5,
                "year": 2035
            }
        },
        "customerAgreement": {
            "type": "installment",
            "installmentType": "latinAmerica",
            "installmentPlan": {
                "numberOfInstallments": 12
            }
        },
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 42
        }
    }
}

Enable additional features

Feature	Description
Fraud assessment	Prevent fraudulent transactions.	How to enable
3DS authentication	Shift Liability to the issuer / for EEA countries this is required as part of SCA compliance.	How to enable
Auto Settlement	Request that payment authorizations are automatically sent for settlement (sometimes referred to as "capture").	How to enable

Response

Flow differences

API responses differ based on the features you have enabled:

If 3DS is enabled you receive a response to perform device data collection and additionally, if prompted by the card issuer, a challenge response.
If FraudSight is enabled, you can receive a fraudHighRisk response, stopping the transaction.
If settlement.auto is set to true, the outcome will be sentForSettlement. If set to false it will be authorized with an addtional settlement action required.

See sequence diagrams to get a clear overview.

Payment response

The payment response contains the following details:

riskFactors (avs/cvc) - if billing address & cvc are provided, these details are checked against the customer's issuing bank
refusal code and description which gives additional context on the refusal
3DS authentication details - details on the 3DS authentication outcome (e.g. challenged)
fraud assessment details - details on the fraud assessment outcome (e.g. lowRisk, review)
Worldpay token creation - details of the card tokenized and the token href itself
paymentInstrument - details of the paymentInstrument used

View the full API Response schema