# CVU transaction

Provision a reusable CVU account, then process online CVU payouts using pay by bank.

## Overview

CVU deposits don't use a standard transaction initiation request. Instead, you provision a reusable CVU account once per shopper, show the CVU or alias in your cashier, and the shopper transfers funds from their own banking app. PXP creates the deposit when the processor notifies it, and sends you the `cvu-transaction-order-executed` webhook as your first and authoritative notice of the deposit.

You can submit a CVU payout in these ways:

- **Payout (withdrawal), new bank account:** Create a pay-by-bank transaction with `apmProvider` set to `Cvu` and `intent` set to `Payout`, and supply all three of `bankAccountNumber`, `bankCode`, and `accountType`. Don't also send `gatewayTokenId`. Capture `fundingData.payByBank.gatewayTokenId` from the response to reuse the destination later.
- **Payout (withdrawal), stored bank account:** Create a payout and supply `gatewayTokenId` from an earlier accepted payout instead of resending bank details.


CVU supports `ARS` only and shoppers in Argentina (`countryCode` `AR`). Treat merchant webhooks as the authoritative final outcome. There's no hosted redirect step for CVU. [Learn more about webhooks](/guides/get-started/about-webhooks).

## Provision a CVU

/v1/transaction-contexts

Use the following request to provision a reusable CVU account for a shopper. The call creates no transaction. Only `merchant`, `site`, and `shopperId` are always required. When you need the provider to create a new CVU, also send the shopper details such as `email`, `firstName`, `lastName`, `documentType`, and `documentNumber`. Omit `apmProvider` or set it to `Cvu`. Values are case-sensitive PascalCase.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "apmProvider": "Cvu",
  "shopperId": "Shopper_AR_01",
  "email": "maria.lopez@example.com",
  "firstName": "Maria",
  "lastName": "Lopez",
  "country": "AR",
  "documentType": "TaxIdNumber",
  "documentNumber": "20123456789",
  "nickName": "maria-lopez"
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (3-50 characters) | Your merchant identifier, as assigned by PXP. |
| `site`string (3-50 characters) | Your site identifier, as assigned by PXP. |
| `apmProvider`string | Identifies the Pay by Bank provider for this provision request. Use `Cvu` for CVU. If you omit `apmProvider`, the gateway treats the request as CVU. Values are case-sensitive PascalCase. |
| `shopperId`string (3-50 characters) | Your unique identifier for this shopper. Together with `merchant` and `site`, it determines which CVU account is returned: there's one active CVU account for each shopper at a given merchant and site. A repeat call with the same three values returns that same account unchanged. |
| `email`string (email, 3-50 characters) | The shopper's email address. Needed when creating a new CVU. |
| `firstName`string (3-50 characters) | The shopper's first name. Needed when creating a new CVU. |
| `lastName`string (3-50 characters) | The shopper's last name. Needed when creating a new CVU. |
| `country`string (2 characters) | The shopper's country, in ISO 3166-1 alpha-2 format. Stored on the context. Not sent to the provider. |
| `documentType`string (3-50 characters) | The shopper identity document type. Needed when creating a new CVU. The gateway accepts any 3 to 50 character string. Use one of these values: `IdentityDocument`, `Passport`, `TaxIdNumber`, `ForeignResidentCard`, or `CivilRegisterId`. |
| `documentNumber`string (3-50 characters) | The shopper identity document number. Needed when creating a new CVU. |
| `nickName`string (3-50 characters) | An optional preferred label used when generating the human-readable `alias` returned in the response. If omitted, the alias is generated without this input. |
| `userName`string (3-50 characters) | The shopper's username. The gateway accepts this field on a CVU provision request but ignores it. |


### Response example

If your request is successful, you'll receive a `200` response with `status` set to `Success`. `transactionContextId`, `status`, and `isEligibleForWithdrawal` are always present. Show the `cvu` or `alias` to the shopper. Store `transactionContextId` if you want to update the alias later. On failure, `status` is `Error` and `errorCode` and `errorMessage` carry the mapped fault detail (never a raw provider code or message). Optional fields are omitted when they have no value, rather than returned as `null`.

```json
{
  "transactionContextId": "3f6f0d0e-6d2a-4b7e-9d3c-1a2b3c4d5e6f",
  "status": "Success",
  "isEligibleForWithdrawal": false,
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "shopperId": "Shopper_AR_01",
  "apmProvider": "Cvu",
  "cvu": "0000003100010000000001",
  "alias": "maria.lopez.cvu",
  "creationDateTime": "2026-08-28T12:00:00Z"
}
```

After you display the CVU, don't call any API when the shopper deposits. Wait for the `cvu-transaction-order-executed` webhook, which creates and confirms the deposit. Deposit notifications may have a null `merchantTransactionId` because there was no merchant create call. [Learn more about webhooks](/guides/get-started/about-webhooks).

## Update a CVU alias

/v1/transaction-contexts/{transactionContextId}/alias

Use the following request to update the human-readable alias for a previously provisioned CVU. The path `transactionContextId` is the authoritative key and must be a GUID. `shopperId` and `cvu` are optional cross-checks. When you omit a cross-check field, the stored value is used. The CVU account number and any prior deposits are unaffected.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "alias": "maria.lopez.updated"
}
```

| Parameter | Description |
|  --- | --- |
| `transactionContextId`string (uuid) | The PXP identifier of the provisioned CVU transaction context, returned by the provision endpoint. Must be a GUID. |
| `merchant`string (3-50 characters) | Your merchant identifier, as assigned by PXP. |
| `site`string (3-50 characters) | Your site identifier, as assigned by PXP. |
| `alias`string (6-20 characters) | The new human-readable alias for the CVU account. 6 to 20 characters of letters, digits, `.`, or `-`. |
| `shopperId`string (3-50 characters) | Optional cross-check against the shopper on the stored context. When omitted, the stored value is used. |
| `cvu`string (22 digits) | Optional cross-check against the 22-digit CVU on the stored context. When omitted, the stored value is used. |
| `documentType`string | Optional shopper identity document type. Allowed values: `IdentityDocument`, `TaxIdNumber`, and `CivilRegisterId`. `Passport` and `ForeignResidentCard` aren't accepted on alias updates. |
| `documentNumber`string (3-50 characters) | Optional shopper identity document number. |


### Response example

If your request is successful, you'll receive a `200` response with `oldAlias` and `newAlias`. `transactionContextId` and `status` are always present. On a failed update, `newAlias` equals `oldAlias`. `creationDate` is the creation time of the owning transaction context, not the time of the alias change. This response has no `stateData`. Optional fields are omitted when they have no value, rather than returned as `null`.

```json
{
  "transactionContextId": "3f6f0d0e-6d2a-4b7e-9d3c-1a2b3c4d5e6f",
  "status": "Success",
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "shopperId": "Shopper_AR_01",
  "cvu": "0000003100010000000001",
  "oldAlias": "maria.lopez.cvu",
  "newAlias": "maria.lopez.updated",
  "creationDate": "2026-08-28T12:00:00Z"
}
```

## Initiate a CVU payout

/v1/transactions

### Request examples

Payout (new bank account)
Use the following request to start a CVU withdrawal when you supply the destination bank account for the first time. Supply all three of `bankAccountNumber`, `bankCode`, and `accountType`. Don't also send `gatewayTokenId`. Capture `fundingData.payByBank.gatewayTokenId` from the response so you can reuse the same destination later.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "CVU-PAYOUT-001",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu",
      "bankAccountNumber": "0000003100010000000001",
      "bankCode": "00007",
      "accountType": "Savings",
      "identifier": "0000003100010000000001",
      "alias": "maria.lopez.cvu"
    }
  },
  "amounts": {
    "transaction": 1400,
    "currencyCode": "ARS"
  },
  "shopper": {
    "id": "Shopper_AR_01",
    "firstName": "Maria",
    "lastName": "Lopez",
    "email": "maria.lopez@example.com",
    "countryCode": "AR",
    "documentType": "TaxIdNumber",
    "documentNumber": "20123456789"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 10 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 50 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce CVU transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For CVU, this is always `PayByBank`. |
| `transactionMethod.intent`string | The payment intent. For a CVU withdrawal, set this to `Payout`. [Learn more about intents](/guides/transactions/how-it-works#intents). |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. For CVU, this must be `ARS`. |
| `fundingData`object | Details about the payment method used for the transaction. For CVU, use the Pay by bank funding shape only. |
| `fundingData.payByBank`object | Pay by bank funding details for CVU. |
| `fundingData.payByBank.apmProvider`string | The APM provider. For CVU, set this to `Cvu`. If omitted, the gateway defaults to `Cvu`. Values are case-sensitive PascalCase. |
| `fundingData.payByBank.bankAccountNumber`string | The destination CVU or CBU account number. Part of the bank-detail set that must be supplied instead of `gatewayTokenId`, never together with it. |
| `fundingData.payByBank.bankCode`string (5 characters) | The destination bank code. Must be exactly 5 characters. Part of the bank-detail set that must be supplied instead of `gatewayTokenId`, never together with it. |
| `fundingData.payByBank.accountType`string | The destination bank account type. Possible values: `Savings`, `Current`. Comparisons are case-sensitive. `Clabe` isn't valid for CVU. Part of the bank-detail set that must be supplied instead of `gatewayTokenId`, never together with it. |
| `fundingData.payByBank.identifier`string (22 digits) | An optional destination 22-digit CVU. Invalid values are rejected with `The identifier field must be a 22-digit CVU.` |
| `fundingData.payByBank.alias`string (1-20 characters) | An optional destination CVU alias. 1 to 20 characters of letters, digits, `.`, or `-`. Invalid values are rejected with `The alias field must be at most 20 characters of letters, digits, '.' or '-'.` |
| `shopper`object | Details about the shopper receiving the payout. |
| `shopper.countryCode`string (2 characters) | The shopper's country, in ISO 3166-1 alpha-2 format. For CVU, this must be `AR`. |
| `shopper.documentType`string | The shopper identity document type. Possible values: `IdentityDocument`, `Passport`, `TaxIdNumber`, `ForeignResidentCard`, `CivilRegisterId`. When supplied, `documentNumber` is also required. |
| `shopper.documentNumber`string | The shopper identity document number. |


Payout (stored bank account)
Use the following request to start a CVU withdrawal when you already have a `gatewayTokenId` from an earlier accepted payout. Send `gatewayTokenId` instead of bank account details. Don't send both.

```json
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "CVU-PAYOUT-002",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu",
      "gatewayTokenId": "b6e2f1a4-c3d8-4f7a-b1e9-d2c3f4a5b6c7"
    }
  },
  "amounts": {
    "transaction": 1400,
    "currencyCode": "ARS"
  },
  "shopper": {
    "id": "Shopper_AR_01",
    "firstName": "Maria",
    "lastName": "Lopez",
    "email": "maria.lopez@example.com",
    "countryCode": "AR",
    "documentType": "TaxIdNumber",
    "documentNumber": "20123456789"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 10 characters) | Your unique merchant identifier, as assigned by PXP. |
| `site`string (≤ 50 characters) | Your unique site identifier, as assigned by PXP. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier for this transaction. |
| `merchantTransactionDate`date-time | The date and time when the transaction happened, in ISO 8601 format. |
| `transactionMethod`object | Details about the transaction method. |
| `transactionMethod.entryType`string | The entry type. For e-commerce CVU transactions, this is always `Ecom`. |
| `transactionMethod.fundingType`string | The funding type. For CVU, this is always `PayByBank`. |
| `transactionMethod.intent`string | The payment intent. For a CVU withdrawal, set this to `Payout`. [Learn more about intents](/guides/transactions/how-it-works#intents). |
| `amounts`object | Details about the transaction amount. |
| `amounts.transaction`number | The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` exponent does not require it (e.g., JPY 1.0). |
| `amounts.currencyCode`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. For CVU, this must be `ARS`. |
| `fundingData`object | Details about the payment method used for the transaction. For CVU, use the Pay by bank funding shape only. |
| `fundingData.payByBank`object | Pay by bank funding details for CVU. |
| `fundingData.payByBank.apmProvider`string | The APM provider. For CVU, set this to `Cvu`. If omitted, the gateway defaults to `Cvu`. Values are case-sensitive PascalCase. |
| `fundingData.payByBank.gatewayTokenId`string | The reference to a stored PXP payment account for the destination bank account. Send this instead of `bankAccountNumber`, `bankCode`, and `accountType`, never with them. Use the `fundingData.payByBank.gatewayTokenId` value from an earlier accepted CVU payout response. |
| `shopper`object | Details about the shopper receiving the payout. |
| `shopper.countryCode`string (2 characters) | The shopper's country, in ISO 3166-1 alpha-2 format. For CVU, this must be `AR`. |
| `shopper.documentType`string | The shopper identity document type. Possible values: `IdentityDocument`, `Passport`, `TaxIdNumber`, `ForeignResidentCard`, `CivilRegisterId`. When supplied, `documentNumber` is also required. |
| `shopper.documentNumber`string | The shopper identity document number. |


### Response example

If your request is successful, you'll receive a `200` response. `fundingData.payByBank.apmProvider` is `Cvu` when returned. Optional fields under `fundingData.payByBank` are omitted when they have no value, rather than returned as `null`.

For a successful CVU payout initiation, expect a `Pending` state with no `redirectUrl`, plus `fundingData.payByBank.paymentId` and `fundingData.payByBank.gatewayTokenId` when stored. `providerTransactionId` and `fundingData.payByBank.processorPaymentId` aren't on the immediate response. They appear on a later query after PXP's background status check has run. `fundingData.payByBank.status` may also appear on query once known — it's the raw provider status. Use the top-level mapped `state` for the transaction outcome.

The final outcome is delivered by a CVU merchant webhook (e.g., `cvu-transaction-order-executed`). [Learn more about webhooks](/guides/get-started/about-webhooks).

Always use the `systemTransactionId` for later PXP API calls against the same transaction. Provider payment identifiers (`providerTransactionId`, `fundingData.payByBank.paymentId`, and `fundingData.payByBank.processorPaymentId`) are for reconciliation and support only. When both are present, `providerTransactionId` and `fundingData.payByBank.processorPaymentId` carry the same value.

```json
{
  "state": "Pending",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "merchantTransactionId": "CVU-PAYOUT-001",
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu",
      "paymentId": "4d2e9f81-5b3c-4a7d-9e6f-1a2b3c4d5e6f",
      "gatewayTokenId": "b6e2f1a4-c3d8-4f7a-b1e9-d2c3f4a5b6c7"
    }
  }
}
```

CVU deposits support a full refund only. Set `fundingType` to `PayByBank`, `apmProvider` to `Cvu`, and `currencyCode` to `ARS`. The refund response doesn't return `fundingData.payByBank`. Use the shared [Refund](/guides/transactions/refund) guide for the request shape and webhook confirmation.