Initializing a Transaction

Overview

Initializing a transaction creates a transaction database entry that you can keep tabs on.

It pre-fetches a transactionId that can be used to get the transaction metadata if a communication error, packet loss, or similar issue occurs while processing it as a sale, refund, authorization, etc. A developer could make an HTTP call to request transaction metadata in order to determine whether the transaction was successful, where transaction initialization is commonly used in combination with GET TRANSACTION metadata.

📘
Did you know?
This functionality falls into the Transaction Management category as it is possible to initialize a transaction and use the database entry transactionId for either processing a CNP or CP transaction subsequently.

Request

POST /api/v4/accounts/{accountId}/payments/init

{}

*Required Scopes: pcx:payments:*, pcx:payments:create

📘
Note
The top-level timestamp is filtered out via data projection for this kind of transaction as it is not necessarily considered as an actual transaction but rather a transaction database entry, as described above. However, there is the trace object that includes the timestamp for this action.
Empty body is required for a successful response.

There are no body parameters that are required for this request. Check out the following optional fields that you can pre-populate for your transaction.

Optional Body Params

Parameter	Type	Description	Example
`description`	`string`	The description for a transaction	`"one-time purchase #10"`
`customer`	`object`	Customer data including, `name`, `email`, `phone`, `billingAddress`.	See Customer.
`shippingAddress`	`object`	Consists of a set of shipping fields such as `"address1`", `"adress2"`, etc.	See Shipping Address.
`level2`	`object`	Level 2 data such as `merchantReference`, `orderId`, etc.	See Level 2.
`level3`	`object`	Level 3 profile data such as: `status`, `transactionSaleTaxRate`, etc.	See Level 3.
`level3ProfileName`	`string`	The name of the Level3 Profile for processing a transaction. See Level 2 and Level 3 Transaction Processing.	`"MyLevel3ProfileName"`
`items`	`array`	Line Item detail for the level 3 data or the level 3 profile name.	See Items.
`trace`	`object`	Trace data of a transaction.	See Trace.
`dynamicDescriptor`	`string`	Name of the dynamic descriptor	`"001DynDesc"`

🚧
Order of Overwriting Customer-Related Information in a PayConex Transaction
Once the merchant fills these fields during transaction initialization, they don't need to be redefined in the transaction processing stage. If personal information, such as customer and shippingAddress, is pre-tokenized via the Checkout Component, they overwrite the fields specified at the time of transaction initialization, and subsequently if the merchant needs to, in the request of a (auth/sale) transaction that is to be processed.
In other words, the order of priority of customer and shippingAddress overwriting is:

Transaction Initialization

Checkout Component Tokenization

Sale Transaction or Authorization Transaction

Here is a summary of what this request does:

Database Entry: Creates a database entry for a transaction prior to processing with some of the fields remaining to be processed such as transaction status, transaction type, etc.
Status Pending: Transaction status is INITIALIZED, which is overwritten by reusing the transactionId to process this transaction as store, sale, auth, credit, refund, and so on.
Tracing Information: Assigns additional "action": "init" to trace.history. This is helpful for debugging purposes if a developer wants to find out if the transaction was previously initialized.

Init Response Example

{
  "transactionId": "000000046526",
  "status": "INITIALIZED",
  "trace": {
    "history": [
      {
        "action": "init",
        "requestId": "91bb9c15-c451-42c3-a237-31fb36f1be6c",
        "correlationId": "42dfbb92-07fd-40dc-9c67-856e91174a13",
        "timestamp": "2025-04-03T07:35:40-05:00"
      }
    ]
  }
}

If we get its transaction metadata,

GET /api/v4/accounts/{accountId}/payments/000000046526

{
  "transactionId": "000000046526",
  "status": "INITIALIZED",
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "init",
        "requestId": "91bb9c15-c451-42c3-a237-31fb36f1be6c",
        "correlationId": "42dfbb92-07fd-40dc-9c67-856e91174a13",
        "timestamp": "2025-04-03T07:35:40-05:00"
      }
    ]
  },
  "amounts": {
    "currency": "USD",
    "approved": "0.00",
    "requested": "0.00"
  },
  "transactionType": "INIT",
  "refundObject": {
    "refundBalance": "0.00"
  }
}

Pre-populating Transaction Metadata

Request

Here is an example of pre-populating the Optional Body Params.

POST /api/v4/accounts/{accountId}/payments/init

{
  "description": "Pre-fetched transaction #1",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "Kansas City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "Kansas City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "level2": {
    "merchantReference": "121231",
    "orderId": "1234567",
    "tax": "0.05",
    "zip": "90210"
  },
  "level3": {
    "summaryCommodityCode": "8012",
    "shipFromZip": "12345"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:create

Response

{
  "transactionId": "000000046726",
  "status": "INITIALIZED",
  "description": "Pre-fetched transaction #1",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "Kansas City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "Kansas City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "level2": {
    "merchantReference": "121231",
    "orderId": "1234567",
    "tax": "0.05",
    "zip": "90210"
  },
  "level3": {
    "status": "PENDING",
    "summaryCommodityCode": "8012",
    "shipFromZip": "12345"
  },
  "trace": {
    "history": [
      {
        "action": "init",
        "requestId": "226376bf-d98b-4a9b-a061-991c8fa2a630",
        "correlationId": "72be2232-12d5-4f8b-a3d8-09d54dc43926",
        "timestamp": "2025-04-03T09:01:02-05:00"
      }
    ]
  }
}

Processing Init Transaction

For more in-depth sections and references, see Credit Card Processing and API Reference.

Using the same transactionId from the Init Response, we subsequently make the following transaction request:

This also prevents accidental potential duplicate charges while giving you flexibility to retry in case of temporary failures without creating another database entry for a transaction.

Request

POST /api/v4/accounts/{accountId}/payments/sale

{
  "transactionId": "000000046526",
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "10.01",
    "currency": "USD"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

📘
Note
As mentioned above, a Card Present Transaction can also take a transactionId in case there is a communication error with the payment processor or similar.

Response

In response, we can see the same transactionId used at the time the transaction was initialized.

Along with the other transaction fields now filled such as transactionType, entryMode, amounts, etc., we also receive "action": "transaction" appended to the trace.history.

For example,

{
  "transactionId": "000000046526",
  "status": "CAPTURED",
  "timestamp": "2025-04-03T14:11:55.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "init",
        "requestId": "91bb9c15-c451-42c3-a237-31fb36f1be6c",
        "correlationId": "42dfbb92-07fd-40dc-9c67-856e91174a13",
        "timestamp": "2025-04-03T07:35:40-05:00"
      },
      {
        "action": "transaction",
        "requestId": "d738dcd1-a627-42ff-af4b-5da3d453cf7e",
        "correlationId": "959ec27c-31d2-4be3-9235-3517b9d09fd7",
        "timestamp": "2025-04-03T09:11:52-05:00"
      }
    ],
    "networkTransactionId": "015093410199274G870"
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.01",
    "requested": "10.01",
    "balance": "10.01"
  },
  "auth": {
    "code": "OK1400",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "10.01"
  }
}

🚧
billingAddress and shippingAddress
As we have used the transactionId from the Init Response Example above, the reason the billingAddress and shippingAddress are populated in this case is they have been pre-tokenized and included in the PayConex™ token during the Checkout Component workflow.
Also see:

Checkout Component Workflow

Processing a Sale | More Complex Sale Transaction

Transaction Workflow

When using the transactionId, we strongly recommend the following workflow for maximum reliability and safety:

1. Transaction Initialization

First, initialize the transaction via the init endpoint.

Benefits:

Creates a transaction record in the system immediately.
Allows you to safely look up the transaction using the transactionId if a communication error, timeout, packet loss, or network issue occurs.
Enables the developer to call the Get Transaction Metadata by ID endpoint to check the current status (e.g., whether the transaction was successfully authorized, declined, or is still pending).

This step acts as a safeguard against duplicate transactions and provides better error recovery.

Request Example

POST /api/v4/accounts/{accountId}/payments/init

{
  "description": "Pre-fetched transaction #02",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "Kansas City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:create

2. Sale / Authorization

Once the transaction is initialized, perform the Sale or Authorization.

Important Behavior:

You can safely retry the Sale or Authorization request multiple times with the same transactionId until the transaction receives a final status (CAPTURED, AUTHORIZED, DECLINED, or another payment state) and there are no network-related errors.
- For all of the transaction statuses, refer to Transaction Metadata | Status.
The transaction will remain in INITIALIZED status until it is successfully processed.
This design also prevents accidental potential duplicate charges while giving you flexibility to retry in case of temporary failures without creating another database entry for a transaction

Request Example

After the transaction was securely stored via the transaction initialization above, we can reuse the transactionId returned in response.

POST /api/v4/accounts/{accountId}/payments/sale

{
  "transactionId": "000000046526",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "10.01",
    "currency": "USD"
  },
  "bfTokenReference": "PAYCONEX_TOKEN"
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

This can either be CNP Sale/Authorization or CP Sale/Authorization.

Error Responses

The error response that stands out from the typical API Reference | Error Responses is that a pre-fetched transaction database entry can be populated once. If we try to use the same transaction id, we receive:

{
  "message": "Transaction ID has already been used",
  "errorCode": 40001,
  "errorType": "invalid_request",
  "traceId": "b3ee5aef-75f0-4f34-a55a-9fe87eef9338"
}