Provision a transaction context

Request

Provisions a reusable Pay by Bank destination for a shopper. Creates no transaction.

The body is a flat JSON object. apmProvider at the root selects how the body is parsed:

Cvu for an Argentine CVU account
Breb for a Colombian Bre-B Llave.

If you omit apmProvider, the gateway treats the request as CVU. Values are case-sensitive PascalCase. An unrecognised or non-string value is rejected with 400 and The apmProvider field is invalid.

Present the returned account details (cvu and alias, or brebKey) so the shopper can push a transfer from their banking app. The final deposit confirmation arrives by merchant webhook.

For CVU, 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.

Bre-B doesn't support alias updates.

Bodyapplication/jsonrequired

apmProviderstring

Identifies the Pay by Bank provider for this provision request. This field selects behaviour: Cvu parses the body as CVU, Breb parses it as Bre-B. Values are case-sensitive PascalCase.

If you omit apmProvider, the gateway treats the request as CVU.

Value:"Cvu"

Example:"Cvu"

Discriminator

merchantstring, [ 3 .. 50 ] charactersrequired

Your merchant identifier, as assigned by PXP.

Example:"MERCHANT-1"

sitestring, [ 3 .. 50 ] charactersrequired

Your site identifier, as assigned by PXP.

Example:"SITE-1"

shopperIdstring, [ 3 .. 50 ] charactersrequired

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.

Example:"Shopper_AR_01"

userNamestring, [ 3 .. 50 ] characters

The shopper's username. The gateway accepts this field on a CVU provision request but ignores it.

Example:"maria.lopez"

emailstring, (email), [ 3 .. 50 ] characters

The shopper's email address. Needed when generating a new CVU.

Example:"maria.lopez@example.com"

firstNamestring, [ 3 .. 50 ] characters

The shopper's first name. Needed when generating a new CVU.

Example:"Maria"

lastNamestring, [ 3 .. 50 ] characters

The shopper's last name. Needed when generating a new CVU.

Example:"Lopez"

countrystring, = 2 characters

The shopper's country, in ISO-3166-1 alpha-2 format. Stored on the context. Not sent to the provider.

Example:"AR"

documentTypestring, [ 3 .. 50 ] characters

The shopper identity document type. Needed when generating a new CVU. Treat as sensitive.

The gateway doesn't enforce a closed list here. Any string in that length range is accepted at this layer. An unrecognised value fails further downstream with a different error.

Use one of these values:

IdentityDocument
Passport
TaxIdNumber
ForeignResidentCard
CivilRegisterId

This list is guidance only. Alias assignment uses a different, enforced set of document types.

Example:"TaxIdNumber"

documentNumberstring, [ 3 .. 50 ] characters

The shopper identity document number. Needed when generating a new CVU. Treat as sensitive.

Example:"20123456789"

nickNamestring, [ 3 .. 50 ] characters

Optional preferred label used when generating the human-readable alias returned in the response. If omitted, the alias is generated without this input.

Example:"maria-lopez"

curl -i -X POST \
  https://api-services.pxp.io/api/v1/transaction-contexts \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
  }'

Responses

Existing or newly provisioned transaction context. Optional fields are omitted when they have no value, rather than returned as null.

Bodyapplication/json

Any of:

Provisioned CVU transaction context. transactionContextId, status, and isEligibleForWithdrawal are always present. Every other field is omitted when it has no value, rather than returned as null. On failure, status is Error and errorCode and errorMessage are PXP-mapped values, never a raw provider code or provider text. This schema is the provision response. Alias updates use cvuAliasResponse.

transactionContextIdstring, (uuid)required

The PXP identifier for the provisioned context. Use this as the path parameter when updating the alias.

Example:"3f6f0d0e-6d2a-4b7e-9d3c-1a2b3c4d5e6f"

statusstringrequired

The merchant outcome of the provision.

Possible values:

Success: a CVU is returned
Error: the operation failed (see errorCode and errorMessage)

Enum:"Success""Error"

Example:"Success"

isEligibleForWithdrawalbooleanrequired

Whether the context is currently eligible for withdrawal. Always present. Reflects the stored value, including on an idempotent replay.

Example:false

merchantstring

Your merchant identifier, as assigned by PXP.

Example:"MERCHANT-1"

sitestring

Your site identifier, as assigned by PXP.

Example:"SITE-1"

shopperIdstring

Your unique identifier for this shopper.

Example:"Shopper_AR_01"

apmProviderstring

The Pay by Bank provider for this context, returned as a plain string.

Example:"Cvu"

cvustring

The 22-digit CVU account number the shopper transfers funds to. Treat as sensitive.

Example:"0000003100010000000001"

aliasstring

The human-readable alias for the same account.

Example:"maria.lopez.cvu"

errorCodestring

PXP-mapped error code. Present only when status is Error. Never a raw provider code.

errorMessagestring

PXP-authored error message. Present only when status is Error. Never raw provider text.

creationDateTimestring, (date-time)

When the transaction context was created, in ISO 8601 or RFC 3339 date-time format.

Example:"2026-08-28T12:00:00Z"

stateDataobject

Additional string-to-string context. Omitted when it has no value.

Response

{
  "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"
}