One-Time Payments

Localpayment enables merchants to process one-time payments using credit and debit cards, across multiple countries and currencies. This guide outlines the process for initiating a one-time card payment through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes.

ℹ️
Prerequisites
An API Key is required to submit a payment request. If you don't have one, contact the Support team to gain access to the Localpayment Panel.

How it Works

The process of executing a payin with a credit or debit card through Localpayment involves the following steps:

Payment Method Selection: Your customer selects the credit/debit card payment method within your application's checkout flow.
Payment Information Collection: Your application securely collects the necessary payment information and any additional required data from the customer. This information is then sent to Localpayment for processing.
Payment Processing: Localpayment processes the payment information.
Transaction Result: Localpayment returns a response to your application with the result of the transaction. If successful, the funds are debited from the customer's card and will be transferred to your Localpayment account.
Confirmation to Customer: Your application displays the transaction result to the customer, allowing them to proceed with their purchase.

Availability

One-time card payment 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 payment request

Before initiating a card payment, 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 Card Payment

When initiating a card payment, 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
- or card token
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 one-time card payment, you'll need to send a POST request to the Create Payin endpoint.

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' \
  --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.

Payment with Tokenized Card

If you have previously tokenized a customer's card, you can use the token instead of sending the full card details to process a one-time payment. This enhances security and simplifies the payment flow by eliminating the need to request card information again.

For detailed information on card tokenization, please refer to the Card Tokenization documentation.

Payment with 3D Secure

If 3D Secure is enabled, Localpayment may redirect the customer to their card issuer's website for authentication. This is an additional security measure to prevent fraud. The specific redirection flow may vary depending on the card issuer and country.

For detailed information on 3D Secure payments, please refer to the 3D Secure documentation.

Payment Status

After initiating a one-time payment, you can track the status of the transaction. The Localpayment API provides various status codes to indicate the progress and outcome of the payment in the response.

Successful Transaction: A successful transaction will typically have a status code of 200 (Completed) or a code indicating approval (e.g., 103).
Failed Transaction: A failed transaction will be indicated by an error status code. The response will include an array of error messages with details about the reason for the failure.

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": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "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., 103 for approved, 100 for pending, 701 for failed).
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.

Next Steps

After a one-time payment 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.

ℹ️Prerequisites

How it Works

Availability

Before a payment request

Request a Card Payment

Payment with Tokenized Card

Payment with 3D Secure

Payment Status

Next Steps

ℹ️
Prerequisites