PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

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

ParameterTypeDescriptionExample
descriptionstringThe description for a transaction"one-time purchase #10"
customerobjectCustomer data including, name, email, phone, billingAddress.See Customer.
shippingAddressobjectConsists of a set of shipping fields such as "address1", "adress2", etc.See Shipping Address.
level2objectLevel 2 data such as merchantReference, orderId, etc.See Level 2.
level3objectLevel 3 profile data such as: status, transactionSaleTaxRate, etc.See Level 3.
level3ProfileNamestringThe name of the Level3 Profile for processing a transaction. See Level 2 and Level 3 Transaction Processing."MyLevel3ProfileName"
itemsarrayLine Item detail for the level 3 data or the level 3 profile name.See Items.
traceobjectTrace data of a transaction.See Trace.
dynamicDescriptorstringName 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:

  1. Transaction Initialization
  2. Checkout Component Tokenization
  3. 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:

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 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:

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