Pre-Authorization

A pre-authorization is a two-step process that allows merchants to verify a customer's payment method before completing a transaction. This process temporarily holds the transaction amount in the customer's account without actually debiting it.

In the first step, the pre-authorization request is made, reserving the specified amount. This ensures that the customer has sufficient funds and that the payment method is valid. However, the funds are not transferred to the merchant at this stage.

In the second step, the capture request is executed to finalize the payment. The pre-authorized amount is then debited from the customer's account and credited to the merchant.

How it Works

The pre-authorization process through Localpayment involves the following steps:

Authorization Initiation: The customer initiates a pre-authorization request within your application by entering their card details and other necessary information.
Payment Information Collection: Your application securely collects the required payment details and transmits them to Localpayment for processing.
Pre-Authorization: Localpayment processes the payment information and, if successful, holds the funds on your customer's card.
Pre-Authorization Result: Localpayment returns a response to your application with the result of the pre-authorization request.
Capture or Cancellation: Your application then sends a capture request to finalize the payment and debit the funds from the customer's account, allowing them to be available in your Localpayment account. Alternatively, you can send a cancellation request to release the held funds back to the customer.
Capture Result: Localpayment returns a response to your application with the result of the capture or cancellation request.
Confirmation to Customer: Your application displays the transaction result to the customer, confirming the payment or cancellation.

Availability

Pre-Authorization processing is available in the following countries:

🇦🇷 Argentina: Visa, Mastercard, American Express, Diners, Argencard, Cabal.
🇧🇴 Bolivia: Visa.
🇧🇷 Brazil: Visa, Mastercard, American Express, Elo, Hipercard.
🇨🇱 Chile: Visa, Mastercard, American Express, Diners, Magna.
🇨🇴 Colombia: Visa, Mastercard, American Express, Diners.
🇩🇴 Dominic Republic: Visa.
🇲🇽 Mexico: Visa, Mastercard, American Express.
🇵🇦 Panama: Visa.
🇵🇪 Peru: Visa, Mastercard, American Express, Diners.

Before a Pre-authorization request

Before initiating a pre-authorization, ensure you have completed the following:

Generate an Access Token (Required): You'll need a valid access token to authenticate your API requests. Refer to the Generate an Access Token documentation for instructions.
Get Available Payment Methods (Required): You must retrieve a list of available payment methods configured for your Localpayment account. This will provide you with the necessary payment method codes. See the Get Available Payment Methods documentation for details.
Validate Identity Document (Optional): You can optionally validate the customer's identity document information before processing the payment. This helps prevent transaction failures and ensures compliance with local regulations. Refer to the Validate Identity Document documentation for more information.
Get BIN Info (Optional): You can optionally validate the card's Bank Identification Number (BIN) to obtain information such as the card brand and card type. This can help you prevent transaction rejections due to invalid card details. See the Get BIN Info documentation for more information.
Get National Holidays (Optional): You can optionally retrieve information about national holidays in the relevant country. This information can be useful for anticipating potential delays in bank processing. See the Get National Holidays documentation for more information.
Generate Currency Exchange Quote (Optional): If you need to process payments in a different currency than your Localpayment account's currency, you can use this step to obtain a currency exchange quote. Refer to the Generate Currency Exchange Quote documentation for details.

Request a Pre-Authorization

When initiating a pre-authorization, it is crucial to accurately gather and securely transmit all necessary payer information. This includes:

Cardholder Details:
- Full name (as it appears on the card)
- Valid card number
- Expiration date
- CVV security code
Payer Information:
- Country-specific identification document
- Contact information (email and phone number)
- Billing address
Transaction Details:
- Payment amount
- Currency (local or foreign)
- Merchant reference ID
Additional Requirements
- 3D Secure authentication (when enabled)
- Merchant-specific metadata

To initiate a pre-authorization, you'll need to send a POST request to the Create Payin endpoint and set the x-capture header to true.

Request Example

Below is an example using curl:

curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --header 'x-capture: true' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "032.032.00000000",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    }
}'

Parameters

paymentMethod: Object with payment method information.
paymentMethod.type: Payment method type. Send DebitCard for debit cards and CreditCard for credit cards.
paymentMethod.code: Payment method code (e.g. 1000).
paymentMethod.flow: Set as DIRECT.
externalId: A unique identifier generated by your system to track the transaction (alphanumeric and hyphens). We recommend using UUID4 to ensure uniqueness (e.g. 40bac59a-0381-4cc0-a6a5-33418d84c2e4).
country: Set the country from which the operation is made. ISO 3166-1 alpha-3 (e.g. ARG).
currency: The currency of the amount can be the local currency (charged directly) or the account's currency (triggering a Foreign Exchange operation), with paymentMethod.code resolving ambiguity in bicurrency countries. E.g. ARS.
amount: Transaction amount (e.g. 1000).
accountNumber: The Localpayment account number where the specified amount will be credited.
conceptCode: Operation concept code (e.g. 0001 for Corporate Payments).
merchant: Information about the merchant initiating the transaction.
merchant.type: Merchant type (e.g. COMPANY).
merchant.name: Merchant name.
merchant.document: Merchant documentation information.
merchant.document.type: The type of identity document, such as a National Identity Number, Social Security Number, or Driver's License, depending on the country of issuance.
merchant.document.id: Identity document number (usually a number). This must be a valid number according to the rules for the specific document type.
merchant.email: Merchant email.
merchant.phone: Object with merchant phone number information.
merchant.phone.countryCode: International country code (e.g. 54).
merchant.phone.areaCode: Area code (e.g. 351).
merchant.phone.number: Phone number (e.g. 1234567).
payer: Object with information about the payer making the transaction.
payer.type: Payer type (e.g. INDIVIDUAL).
payer.name: Payer name.
payer.lastname: Payer last name.
payer.document: Payer documentation information.
payer.document.type: The type of identity document, such as a National Identity Number, Social Security Number, or Driver's License, depending on the country of issuance.
payer.document.id: Identity document number (usually a number). This must be a valid number according to the rules for the specific document type.
payer.email: Payer email.
payer.phone: Payer phone number.
payer.phone.countryCode: International country code.
payer.phone.areaCode: Area code.
payer.phone.number: Phone number.
payer.bank: Payer's banking information.
payer.bank.name: Bank name.
payer.bank.code: Bank code.
payer.bank.account: Bank account information.
payer.bank.account.type: Payer account type (e.g. S for Saving account).
payer.bank.account.number: Payer account number.
commercialData: Object with commercial details about the transaction.
commercialData.items: Array of items included in the transaction.
commercialData.items.id: A unique identifier for the item.
commercialData.items.quantity: The quantity of this item purchased.
commercialData.items.description: A description of the item.
commercialData.items.title: The title or name of the item.
commercialData.items.unitPrice: The price per unit of the item.
card: Object with card payment information.
card.name: Cardholder name.
card.number: Card number (PAN).
card.cvv: Card Verification Value.
card.expirationMonth: Card expiration month. Format MM.
card.expirationYear: Card expiration year. Format YYYY.

See all available parameters in the request.

Successful response example

{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "032.032.00000000",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "032.032.00000001"
  },
  "status": {
    "code": "102",
    "description": "AUTHORIZED",
    "detail": "The payin was authorized"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37895247",
      "type": "DNI"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "bin": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}

Key Fields in the Response

externalId: A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining transaction information or making a refund.
internalId: A unique identifier for the transaction in Localpayment’s system.
paymentMethod: Details about the payment method used.
status: Object with information about the status of the transaction.
status.code: The status code (e.g., 102 for AUTHORIZED).
date: Timestamps for when the transaction was created and processed.

For a complete list of status codes and their meanings, please refer to the Transaction Status documentation.

Localpayment also sends webhooks to your application to notify you of changes in the transaction status. For more information on webhooks, please refer to the Webhooks documentation.

Capture the funds

After pre-authorizing a transaction, you must capture the funds to debit the customer's account. Ensure that the capture request is for the full amount of the pre-authorization. The pre-authorization hold on the funds will expire after 7 days. If you do not capture the funds within this period, they will be automatically released back to the customer's card.

To capture a pre-authorization, send a PATCH request to the Capture Authorized Payin endpoint.

Request Example

curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/capture/{externalId}' \
--header 'Authorization: Bearer <your_access_token>'

Successful Response Example

{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "40ae5d95-e859-4fc9-b37b-67442392b785",
    "status": {
        "code": "103",
        "description": "APPROVED",
        "detail": "The payin was confirmed but not credited yet"
    }
}

Release Unused Funds

In order to ensure a positive customer experience, it is recommended to release any pre-authorized funds that will not be used. By initiating a release through an API request, you can avoid having your customers wait the full 7 days for the automatic release.

To release unused funds, send a PATCH request to the Cancel Payin Authorization endpoint.

Request Example

curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/capture/{externalId}/status/' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "CANCELLED"
}'

Successful Response Example

{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "39eb0371-3f21-488f-a779-913799e51406",
    "status": {
        "code": "905",
        "description": "CANCELLED",
        "detail": "The authorization was cancelled"
    }
}

Next Steps

After a pre-authorization is processed, you may need to perform additional actions, such as:

Refund the transaction: If necessary, you can refund the payment to the customer. Refer to the Refunds documentation for details.
Handle chargebacks: In case of a dispute, you may need to handle chargebacks. Refer to the Chargebacks documentation for information on this process.
Review transaction details: You can retrieve transaction information using the Localpayment API. See the Transaction Information documentation for details.