Create a cash payment

Localpayment enables merchants to process payments through cash networks, allowing customers to pay with physical currency at authorized locations. This guide outlines the process for initiating cash payments through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes for seamless integration with cash payment networks.

Note: Cash payments expire in 7 days by default. The expiration period can be adjusted between 1-7 days by contacting our support team.

Before You Begin

Ensure you have:

API Credentials

Valid API credentials and access token for authentication.

Account Setup

Proper account setup for your target country and business verification.

Country Requirements

Understanding of country-specific requirements and local regulations.

Step 1: Create Cash Payment

To generate a cash payment reference, send a POST request to the Create Payin endpoint with cash-specific parameters.

Key Request Parameters

The request requires several key parameters specific to cash payments:

Object	Description	Required
`paymentMethod.type`	Must be `Cash`	✅
`paymentMethod.code`	Cash payment method code (country-specific)	✅
`payer`	Payer information for compliance	✅
`merchant`	Merchant/business details	✅
`amount`	Transaction amount	✅
`currency`	Transaction currency code	✅
`country`	Country code where payment will be made	✅

See all available parameters in the request.

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
    "paymentMethod": {
        "type": "Cash",
        "code": "1801",
        "flow": "DIRECT"
    },
    "externalId": "f3913fda-c33b-494a-a134-9d37f0421e2a",
    "country": "GTM",
    "amount": 1001.0,
    "currency": "GTQ",
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0003",
    "comment": "Add any relevant information related to the transaction",
    "merchant": {
        "type": "COMPANY",
        "name": "My merchant",
        "document": {
            "type": "NIT",
            "id": "36029785"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
		"name": "John",
		"lastname": "Doe",
        "email": "[email protected]",
		"document": {
			"id": "3463426000101",
			"type": "CUI"
		}
    }
}
'

Step 2: Handle the Response

Successful Response

A successful cash payment creation includes the payment reference and cash network details:

{
    "transactionType": "PayIn",
    "externalId": "f3913fda-c33b-494a-a134-9d37f0421e2a",
    "internalId": "775558a4-7a71-4163-bc02-5bf6faa45c0b",
    "paymentMethod": {
        "type": "Cash",
        "code": "1801",
        "flow": "DIRECT"
    },
    "country": "GTM",
    "currency": "GTQ",
    "amount": 1001.0,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "GTQ",
        "amount": 1001.0,
        "fxQuote": 1.0
    },
    "payment": {
        "currency": "GTQ",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 1001.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "GTQ",
        "fxSource": 7.66433259,
        "fxQuote": 1.0,
        "amount": 0.0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "The payin is pending the confirmation"
    },
    "ticket": {
        "image": "https://api.stage.localpayment.com/api/images/Code128/4201762961253259",
        "barcode": "4201762961253259",
        "expirationDate": "2025-11-19T15:27:32.8241946"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "My merchant",
        "document": {
            "type": "NIT",
            "id": "36029785"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "CUI",
            "id": "3463426000101"
        },
        "email": "[email protected]"
    },
    "intermediaries": [],
    "date": {
        "creationDate": "2025-11-12T15:27:30.888+00:00",
        "processedDate": "2025-11-12T15:27:33.3566208",
        "expirationDate": "2025-11-19T15:27:32.8241946"
    },
    "errors": []
}

Key Response Fields

Parameter	Description	Use Case
`ticket.image`	URL to the barcode image	Display scannable barcode to customer.
`ticket.barcode`	Barcode numeric value	Alternative to image for barcode generation.
`ticket.expirationDate`	When the payment ticket expires	Display countdown and handle expiration.
`externalId`	Your original reference number	Internal reconciliation and tracking.
`status.code`	Current transaction state (`100` = `INPROGRESS`)	Determine next steps in payment flow.
`date.creationDate`	When transaction was created.	Analytics and performance tracking.

Error Response

When cash payment creation fails, you'll receive detailed error information:

{
    "externalId": "f3913fda-c33b-494a-a134-9d37f0421e2a",
    "internalId": "899b95ed-64b0-4d61-8203-734792707dbf",
    "status": {
        "code": "300",
        "description": "REJECTED"
    },
    "errors": [
        {
            "code": "300",
            "detail": "Invalid param + [payer.email] + must not be null"
        }
    ]
}

Step 3: Present Payment Instructions to Customer

After successfully creating a cash payment, provide clear instructions to the customer:

Display Payment Ticket: Show the barcode image prominently.
Provide Barcode Number: Display the numeric barcode value as alternative.
Set Expiration Expectations: Clearly communicate the payment deadline.
Provide Step-by-Step Guide: Explain the payment process at authorized locations.
Include Support Information: Provide customer support contact details.

Best Practices for Payment Presentation

Display barcode image in high resolution for easy scanning.
Show numeric barcode value as backup for manual entry.
Include clear expiration date and countdown timer.
Provide instructions for payment location procedures.
Send payment reminders as expiration approaches.
Ensure mobile-responsive display for on-the-go customers.

Step 4. Track Transaction Status

After initiating a cash payment, monitor its progress through these methods:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Status Codes

The Localpayment API provides various status codes to indicate the progress and outcome of cash payments.

Code	Status	Description
`100`	`INPROGRESS`	Payment ticket created, waiting for customer payment.
`300`	`REJECTED`	Invalid params

📝
Note: For complete status code reference, see the Transaction Status documentation.

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

Successful Payment Creation: Generate valid cash payment tickets with barcodes
Payment Expiration: Handle expired payment tickets gracefully
Duplicate External ID: Manage duplicate reference errors
Status Updates: Webhook handling and status polling.

Next Steps

After creating a cash payment, you may need to perform additional actions:

Cancel Cash Payment

Cancel pending cash payments before they are paid by customers.

Refund Cash Payment

Process refunds for completed cash payments.

Check Payment Status

Monitor the status of cash payments and track completion.