Virtual Account with Payment Intent

Virtual Account with Payment Intent assigns a CVU (Cuenta Virtual Uniforme) to each transaction, tied to a specific amount and expiration time. Unlike a standard virtual account that accepts any deposit, this product only confirms the PayIn when the payer transfers exactly the indicated amount before the expiration date.

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.

IP Whitelisting

Whitelist your server IP addresses for API access.

Webhook Endpoint

Set up a webhook URL to receive payment notifications.

How It Works

The flow differs from the standard CVU virtual account in one key aspect: each payment is assigned a CVU bound to a specific amount.

Your system calls POST /api/payin/ with paymentMethod.code: "1060" and the expected amount.
Localpayment returns a unique CVU, the beneficiary bank details, and an expiration date.
You display the CVU, the exact amount, and the expiration deadline to the payer.
The payer initiates a bank transfer to the CVU from their banking app or wallet.
When the transfer arrives with the exact amount before expiration, Localpayment confirms the PayIn and sends a webhook to your system.

Step 1: Create a Payment Intent

Send a POST request to the Create Payin endpoint.

Request

Parameter	Type	Description	Required
`externalId`	string	Unique identifier for this transaction in your system. Use UUID4 format.	✅
`accountNumber`	string	Your Localpayment account number.	✅
`country`	string	Must be `ARG`.	✅
`currency`	string	Must be `ARS`.	✅
`amount`	number	The exact amount the payer must transfer.	✅
`paymentMethod.type`	string	Must be `BankTransfer`.	✅
`paymentMethod.code`	string	Must be `1060`.	✅
`paymentMethod.flow`	string	Must be `DIRECT`.	✅
`payer.type`	string	`INDIVIDUAL` or `COMPANY`.	✅
`payer.name`	string	Payer's first name.	✅
`payer.lastName`	string	Payer's last name. Required when `type` is `INDIVIDUAL`.	✅
`payer.document.type`	string	Document type, e.g. `DNI` or `CUIT`.	✅
`payer.document.id`	string	Document number.	✅
`payer.email`	string	Payer's email address.
`merchant`	object	Merchant/business details.	✅

Example Request

curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "accountNumber": "{{yourAccountNumber}}",
  "country": "ARG",
  "currency": "ARS",
  "amount": 5000.00,
  "conceptCode": "0003",
  "comment": "Add any relevant information related to the transaction",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1060",
    "flow": "DIRECT"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name",
    "document": {
      "type": "CUIT",
      "id": "30000000000"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "87654321"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20000000000"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    },
    "birthdate": "1990-01-01",
    "nationality": "ARG"
  }
}'

Successful Response

{
  "transactionType": "PayIn",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1060",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 5000.00,
  "accountNumber": "{{yourAccountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "fxQuote": 1,
    "amount": 5000.00
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 5000.00
  },
  "localTaxes": [],
  "withHoldings": [],
  "grossingUps": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0,
    "account": "{{yourAccountNumber}}"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name",
    "document": {
      "type": "CUIT",
      "id": "30000000000"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "87654321"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20000000000"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    },
    "birthdate": "1990-01-01",
    "nationality": "ARG"
  },
  "wireInstructions": {
    "beneficiary": {
      "type": "COMPANY",
      "name": "LOCALPAYMENT S.R.L.",
      "document": {
        "type": "CUIT",
        "id": "30716132028"
      },
      "bank": {
        "code": "000",
        "branch": {
          "code": "036"
        },
        "account": {
          "number": "0000000000000000000000"
        }
      }
    },
    "referenceCode": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526"
  },
  "date": {
    "creationDate": "2024-01-15T10:30:00Z",
    "processedDate": "2024-01-15T10:30:01Z",
    "expirationDate": "2024-01-22T10:30:00Z"
  },
  "errors": []
}

Key Response Fields

Field	Description
`wireInstructions.beneficiary.bank.account.number`	The unique CVU to which the payer must transfer funds.
`wireInstructions.beneficiary.bank.name`	Name of the receiving bank.
`date.expirationDate`	Deadline by which the payer must complete the transfer.
`status.code`	`100` (INPROGRESS) on creation. Transitions to `200` (COMPLETED) or `300` (REJECTED) via webhook.

Error Response

{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [document.id] + verification failed"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [document.id] + verification failed"
    }
  ]
}

Step 2: Display Payment Instructions to the Payer

Once you receive the response, show the following to the payer:

CVU: the value from wireInstructions.beneficiary.bank.account.number
Amount: the exact amount from your request. The payer must send this precise figure.
Expiration: the deadline from date.expirationDate
Beneficiary name: the value from wireInstructions.beneficiary.name (Localpayment S.R.L. as the registered account holder)

ℹ️
If the payer transfers a different amount, the transfer is credited as a standard virtual account PayIn and does not confirm the payment intent.

Step 3: Handle Payment Notifications

Unlike a standard virtual account (where you only receive a webhook when a payment is credited), Payment with Intention triggers two webhook events:

Creation notification (INPROGRESS): fires immediately when the payment intent is created, containing the assigned CVU and expiration date in wireInstructions. Your system can use this to confirm the CVU assignment.
Completion notification (COMPLETED): fires when the payer's transfer is processed and the exact amount is received before expiration.

Completion Notification (COMPLETED)

{
  "transactionType": "PayIn",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1060",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 5000.00,
  "accountNumber": "{{yourAccountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "fxQuote": 1.0,
    "amount": 5000.00
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1.0,
    "financingFee": 0.0,
    "amount": 5000.00
  },
  "localTaxes": [
    {
      "code": "0001",
      "percentage": 1.2,
      "description": "IDC",
      "currency": "ARS",
      "fxSource": 1,
      "fxQuote": 0.0,
      "amount": 60.00,
      "account": "{{yourAccountNumber}}"
    }
  ],
  "withHoldings": [],
  "grossingUps": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0.0,
    "account": "{{yourAccountNumber}}"
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "The payin was credited"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Merchant Name",
    "document": {
      "type": "CUIT",
      "id": "30000000000"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "87654321"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastName": "Doe",
    "document": {
      "type": "CUIT",
      "id": "20000000000"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "11",
      "number": "12345678"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "Buenos Aires",
      "state": "Buenos Aires",
      "country": "ARG",
      "zipCode": "1000"
    },
    "birthdate": "1990-01-01",
    "nationality": "ARG"
  },
  "wireInstructions": {
    "beneficiary": {
      "type": "COMPANY",
      "name": "LOCALPAYMENT S.R.L.",
      "document": {
        "type": "CUIT",
        "id": "30716132028"
      },
      "bank": {
        "code": "000",
        "branch": {
          "code": "036"
        },
        "account": {
          "number": "0000000000000000000000"
        }
      }
    },
    "referenceCode": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526"
  },
  "date": {
    "creationDate": "2024-01-15T10:30:00Z",
    "processedDate": "2024-01-15T10:38:22Z",
    "expirationDate": "2024-01-22T10:30:00Z"
  },
  "errors": []
}

Test in Stage

Use the Simulate Virtual Account Payment endpoint to test end-to-end in Stage without making real bank transfers.

Simulate a successful payment using paymentMethod.code: "1060" and the same externalId returned in the creation response.

Demo

Next Steps

Receive Payment Notifications

Configure your webhook endpoint and learn how to verify and handle PayIn notifications for virtual account payments.

Get Transaction Status

Poll the transaction status endpoint to check the current state of a payment intent.

Simulate a Payment

Test your integration end-to-end in Stage without real bank transfers.

Virtual Accounts Overview

Learn about all virtual account products and their use cases.