Cash Payments

Cash payments allow customers to generate a payment order and complete the transaction using cash at a designated payment location. When a cash payment order is created, it remains in the INPROGRESS status until it is successfully paid, manually canceled, or reaches its expiration date.

By default, a cash payment order expires after 7 days. However, the expiration period can be adjusted between 1 and 7 days based on your business needs.

How it Works

The process of handling a cash payment through Localpayment involves the following steps:

Customer Initiates Payment: Your customer selects the bank transfer option during checkout.
Payment Request: Your application sends a payment request to the Localpayment API, specifying the payment method, amount, currency, and other relevant details.
Provide Instructions: Localpayment generates payment instructions, including unique reference and payment details.
Payment Execution: The customer visits a participating payment location (e.g., convenience store) and provides the voucher to complete the payment.
Notification: Once the payment is made, the merchant is notified, and the order is processed.

Availability

Cash payment processing is available in the following countries:

🇦🇷 Argentina: Pago Fácil, Rapipago.
🇧🇷 Brazil: Boleto, Pec.
🇨🇱 Chile: Express Lider, Acuenta, Banco Estado Expres, Caja Vecina, Lider, Destacame.cl, Redelcom, Sencillito, Fullcarga, Maxservicios and more..
🇨🇴 Colombia: JER, Megared, Mafephone, Coopenessa, Apuestas Nacionales, Gana, Fullcarga, Apuestas Cúcuta 75, Pequeña Superficies Credibanco and more.
🇨🇷 Costa Rica: Banco Popular, Agentes Unipuntos, Tiendas Ekono Punto Físico, Banco Nacional, Puntos Hey and more..
🇬🇹 Guatemala: Fundación Génesis, AKISI Puedo, Super 24, Banco G&T Continental, BAM.
🇲🇽 Mexico: Farmacias Bazar, Superama, Afirme, Banco Azteca, Farmacias Benavides, Bodega Aurrera, Oxxo, 7-Eleven, Circle K and more.
🇵🇦 Panama: El Machetazo, Jumbo supermercados, Western Union, Super Xtra and more.
🇵🇪 Peru: Niubiz por WU (Puntos Fisicos), IZZIPAY, YAPE, Interbank, Banco Pichincha, Western Union and more.

Before a Payment Request

Before initiating a cash payment, make sure you have completed the following steps:

Generate an Access Token (Required): A valid access token is required to authenticate your API requests. Refer to the Generate an Access Token documentation for detailed instructions.
Retrieve Available Payment Methods (Required): You must obtain a list of available cash payment methods configured for your Localpayment account. This list provides the necessary payment method codes. See the Get Available Payment Methods documentation for more details.
Retrieve Payment Concept Codes (Required): Obtain the list of available payment concept codes. You will need to include the appropriate code in your payment request.
Validate Identity Document (Optional): You may choose to validate the customer's identity document before processing the payment. This step helps prevent transaction failures and ensures compliance with local regulations. For more details, refer to the Validate Identity Document documentation.
Check National Holidays (Optional): You can retrieve information about national holidays in the target country. This can help anticipate potential delays in payment processing. See the Get National Holidays documentation for more information.

Request a Cash Payment

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

Payer Information:
- Full name
- Country-specific identification document
Transaction Details:
- Payment amount
- Currency (local or foreign)
- Merchant reference ID
Additional Requirements
- Merchant-specific metadata

To initiate a cash payment, you'll need to send a POST request to the Create Payin endpoint. Ensure that you specify the payment method type as Cash.

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": "Cash",
        "code": "1008",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "032.032.00000000",
    "conceptCode": "0003",
    "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"
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    }
}'

Parameters

paymentMethod: Object with payment method information.
paymentMethod.type: Payment method type. Send Cash for cash payments.
paymentMethod.code: Payment method code (e.g. 1008).
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.
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.

See all available parameters in the request.

Successful response example

If the request is successful, the API will return the necessary information for the payment within the ticket object.

{
    "transactionType": "PayIn",
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "cba93d21-0df3-4694-b219-9d6458c75b9a",
    "paymentMethod": {
        "type": "Cash",
        "code": "1008",
        "flow": "DIRECT"
    },
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000.0,
    "accountNumber": "032.032.00000000",
    "confirmed": {
        "currency": "ARS",
        "fxQuote": 1.0,
        "amount": 1000.0
    },
    "payment": {
        "currency": "ARS",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 1000.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "ARS",
        "fxSource": 110.122017,
        "fxQuote": 1.0,
        "amount": 42.0,
        "account": "032.032.00000001"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "The payin is pending the confirmation"
    },
    "ticket": {
        "id": "1111111111",
        "image": "https://api.stage.localpayment.com/api/images/1003/6002203236005007849112630060030590730000050007",
        "barcode": "3335008800000000006001885552100005200211740749",
        "expirationDate": "2025-03-31 12:49:46.298623"
    },
    "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"
        }
    },
    "intermediaries": [],
    "date": {
        "creationDate": "2025-03-24T12:49:45.465+00:00",
        "processedDate": "2025-03-24 12:49:46.298623",
        "expirationDate": "2025-03-31 12:49:46.298623"
    },
    "errors": []
}

Key Fields in the Response

The response includes essential fields that provide details about the transaction. These include:

externalId: A unique identifier for the transaction in your system. It will be used to perform other operations such as obtaining transaction information.
internalId: A unique identifier for the transaction in Localpayment’s system.
status: Object with information about the status of the transaction.
status.code: The status code (e.g., 100 for INPROGRESS).
date: Timestamps for when the transaction was created and processed.
ticket: Object containing payment reference details.
ticket.id: Unique identifier of the payment reference.
ticket.image: Image of the payment reference (if available).
ticket.barcode: Barcode of the payment reference (if available).
ticket.expirationDate: Expiration date of the payment reference.
ticket.paymentInstructions: Payment instructions (if available).

The properties included in the response may vary depending on the selected payment method.

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.

Payment Reference Generation

After a successful cash payment request, it is necessary to generate a payment reference (e.g., in PDF or image format) for the customer to use at a designated payment location.

How to Pay

To complete the payment, the customer must visit a designated payment location. Once the payment is successfully processed, Localpayment will send a notification to your application with the updated status.

Cancel a Cash Payment

To cancel a cash payment, you'll need to send a PATCH request to the Cancel a Payin endpoint.

Request Example

Below is an example using curl:

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

Parameters

status: Send the value CANCELLED to cancel a cash payment.

Successful response example

{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "764355d7-9935-4716-8e26-0f507ba2e6f8",
    "status": {
        "code": "900",
        "description": "CANCELLED",
        "detail": "The payin was cancelled"
    }
}

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
internalId: A unique identifier for the transaction in Localpayment’s system.
status: Object with information about the status of the transaction.
status.code: The status code (e.g., 900 for CANCELLED).

Next Steps

After a cash 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.