Bank transfer

Bank transfers are a secure and widely used payment method that allows customers to transfer funds directly from their bank accounts to complete a transaction. When initiating a bank transfer request, the response will include the wireInstructions object, which contains the payment details your customer must use to complete the transfer.

Once a bank transfer payment order is created, it will remain in the INPROGRESS status until it is successfully paid, manually canceled, or expires.

By default, a bank transfer payment order expires after 7 days. However, you can adjust the expiration period to any value between 1 and 7 days to suit your business needs. If you require a different expiration period, please contact our support team for assistance.

How it Works

The process of executing a pay-in with bank transfer 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 bank details and a unique reference number.
Customer Transfer: The customer uses their online banking platform or visits a bank branch to initiate the transfer.
Notification: Localpayment verifies the transfer and notifies you of the successful payment.

Availability

Bank transfer payments are supported in the following countries:

🇦🇷 Argentina
🇧🇴 Bolivia
🇧🇷 Brazil
🇨🇱 Chile
🇨🇴 Colombia
🇨🇷 Costa Rica
🇩🇴 Dominic Republic
🇬🇹 Guatemala
🇲🇽 Mexico
🇵🇦 Panama
🇵🇪 Peru

Before Initiating a Bank Transfer

Before requesting a bank transfer payment, ensure you have completed the following steps:

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.
Get 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 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 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.

Request a Bank Transfer

When requesting a bank transfer payment, it is essential to accurately collect and securely transmit all required 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 bank transfer payment, you'll need to send a POST request to the Create Payin endpoint. Ensure that the paymentMethod.type parameter is set to BankTransfer.

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": "BankTransfer",
        "code": "1699",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "484.484.00000058",
    "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": "CURP",
            "id": "123456789000000000"
        },
        "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 BankTransfer for cash payments.
paymentMethod.code: Payment method code (e.g. 1699).
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. MEX).
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. MXN.
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 a wireInstructions object in the response. This object contains the necessary information for the customer to complete the payment.

{
    "transactionType": "PayIn",
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "d147a22c-5c33-4038-a5f5-af5b1f7b4e69",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1699",
        "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000.0,
    "accountNumber": "484.484.00000058",
    "confirmed": {
        "currency": "MXN",
        "amount": 1000.0,
        "fxQuote": 1.0
    },
    "payment": {
        "currency": "MXN",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 1000.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "MXN",
        "fxSource": 20.35926491,
        "fxQuote": 21.37722815,
        "amount": 32.07,
        "account": "484.484.00000058"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "The payin is pending the confirmation"
    },
    "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": "CURP",
            "id": "123456789000000000"
        },
        "email": "[email protected]",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        }
    },
    "intermediaries": [],
    "wireInstructions": {
        "beneficiary": {
            "bank": {
                "name": "Sistema de Transferencias y Pagos STP",
                "code": "0031",
                "branch": {},
                "account": {
                    "type": "C",
                    "number": "646180310000000000"
                }
            },
            "name": "MEXIPAGOS SA",
            "document": {
                "type": "RFC",
                "id": "MEX2003191F4"
            }
        }
    },
    "date": {
        "creationDate": "2025-04-01T15:22:16.549+00:00",
        "processedDate": "2025-04-01T15:22:16.8592249",
        "expirationDate": "2025-04-08T15:22:16.8520254"
    },
    "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.
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., 100 for INPROGRESS).
date: Timestamps for when the transaction was created and processed.
wireInstructions: Details about the payment instructions.
wireInstructions.beneficiary.bank: Information about the beneficiary's bank account for receiving the transfer.
wireInstructions.beneficiary.bank.name: Name of the beneficiary bank.
wireInstructions.beneficiary.bank.account: Beneficiary's bank account details.
wireInstructions.beneficiary.referenceCode: Transaction reference number.
wireInstructions.beneficiary.: Payment instructions (if available).

The properties returned in the response may vary depending on the selected payment method. Refer to the full list of response properties for details.

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 Instructions

After a successful bank transfer request, you must provide the payment reference returned in the response, along with any other information required for the customer to complete the payment. Display clear instructions and specify that the customer must initiate the fund transfer from their bank account to the provided account details.

How to Pay

The customer must initiate a bank transfer using the provided payment details through their bank's application. Once the payment is successfully processed, Localpayment will send a notification to your application with the updated status.

Cancel a Bank Transfer Payment

To cancel a bank transfer 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 bank transfer 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 bank transfer 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.