Every payment Preczn processes — a charge, a hold, a cancellation, a refund — goes through one endpoint: POST /v1/transactions. The type property in the request body decides which one you get.

Choosing a type

A seventh type, drawdown, draws against an approved consumer loan rather than a payment method. See Loan Transactions.

Sale, or Auth then Capture?

A sale is final: it transfers funds from the customer's account to the merchant's account in a single step. An auth only confirms the funds are available and places a temporary hold on them — nothing reaches the merchant until you follow it with a capture.

Reach for auth and capture when time passes between the customer agreeing to pay and you being able to fulfil. Delayed shipping is the common case: authorize at checkout, capture when the goods ship, and the customer is charged only at that point.

A sale behaves like an auth and a capture submitted at the same moment.

Void, or Refund?

Both undo a transaction. Which one applies depends entirely on whether that transaction has settled.

A void cancels a transaction that has not yet settled, so it can be run immediately after an erroneous transaction. A refund returns money from a transaction that has settled — which is usually no earlier than the next day.

Building the request

The endpoint and the response shape are the same for every type. What changes is which fields you have to send.

What each type requires

That splits the six types into two request shapes:

• Transactions against a payment method — sale, verify, and auth name the merchant and carry the payment credentials, either as raw card data or as a token.
• Follow-on transactions — capture, void, and refund carry only the id of the transaction they act on. Merchant, payment method, and currency are all inherited from it.

amount is optional on capture and refund, where sending one means acting on part of the original transaction rather than all of it.

📘

Amounts are integers in the lowest currency denomination

Send 145 to charge $1.45 USD, or 100 to charge ¥100 in a zero-decimal currency.

What comes back

Every type returns the same transaction object. Below is an approved sale routed to Stripe.

{
    "amount": 145,
    "authorization": {
        "approvedAmount": 145,
        "avs": "U",
        "cvv": "M",
        "partial": false,
        "processorCode": "approved_by_network",
        "processorMessage": "Payment complete.",
        "processorTransactionId": "ch_3MeKMMAzKBz0Hugp0OhsoRNi",
        "status": "A"
    },
    "createdOn": "2023-02-22T15:35:57Z",
    "currency": "USD",
    "fee": 0,
    "id": "txn_h1rn8c9nd81y9bkgzax2k2rax",
    "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
    "payment": {
        "bin": "432100",
        "brand": "VISA",
        "last4": "0012",
        "type": "CREDIT"
    },
    "plan": {
        "id": "plan_57jaev7pna8nftrkr6xksaastw",
        "name": "Stripe Only Plan"
    },
    "platformId": "pfm_7aj2pxrrcg8zs8x6cxyyrwmyqe",
    "processor": {
        "id": "midCon_6v59stftbs837axmpahj21m8jf",
        "name": "Stripe"
    },
    "type": "sale"
}

What differs by type:

• capture, void, and refund responses add originalTransactionId — the id of the transaction they acted on — and a message summarizing the outcome.
• authorization.partial is true when only part of the original amount was captured or refunded.
• A verify response carries no amount or approvedAmount; there is nothing to charge.
• An auth response describes a hold rather than a completed payment, so authorization.processorCode and processorMessage carry the processor's own hold vocabulary. For Stripe, that is payment_intent and requires_capture.

📘

Verification results

authorization.cvv and authorization.avs carry the card verification and address verification results. See CVV and AVS for how Preczn maps each processor's codes.

Type reference

Sale

A Sale charges a customer's payment method for the purchase of goods or services, transferring funds from the customer's account to the merchant's account.

{
    "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
    "type": "sale",
    "payment": {
        "token": "tkn_5kpqt630zh9kdrev2kxmdr66tr"
    },
    "amount": 145
}

{
    "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
    "type": "sale",
    "payment": {
        "number": "4321000000000012",
        "cvv": "123",
        "expiration": "1235"
    },
    "amount": 145
}

Verify

A Verify validates a customer's payment method without charging it. Each processor handles this differently, but most run a $0.00 authorization against the account to establish its validity.

The common use is exchanging a single-use token — obtained through a PaymentFields Integration — for a multi-use token you can store and reuse later. To learn more about tokens, see Tokenization.

📘

Getting a multi-use token back

Include the ?tokenize=true query parameter in your Process Transaction request. Without it, an approved verify returns no multi-use token.

{
    "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
    "type": "verify",
    "payment": {
        "number": "4321000000000012",
        "cvv": "123",
        "expiration": "1235"
    }
}

Auth

An Auth (Authorization) confirms that the customer has funds available to cover a potential purchase and places a temporary hold on them. It does not transfer funds to the merchant.

To complete the transaction and move the money, follow the Auth with a Capture.

{
    "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
    "type": "auth",
    "payment": {
        "number": "4321000000000012",
        "cvv": "123",
        "expiration": "1235"
    },
    "amount": 125
}

Capture

A Capture settles a previously approved Auth for funding. At minimum it needs type set to capture and transactionId set to the id of the Auth you are capturing.

• A Capture must run against a previously approved Auth.
• A Capture can be processed for a different amount than the Auth authorized, and may carry additional transaction details that override the original authorization.
• Capturing above the originally authorized amount is only permitted where tipping is enabled — restaurants, for example — and is still processed as a partial capture.

Partial capture

To capture only part of an authorization, include an amount lower than the original. Only that amount is captured.

🚧

Follow-on captures

Some connections allow multiple partial captures, up to the remaining authorization balance.

Others do not permit subsequent captures on a single authorization. On those, each additional transaction requires a new authorization before it can be captured.

{
    "type": "capture",
    "transactionId": "txn_h1rn8c9nd81y9bkgzax2k2rax"
}

{
    "type": "capture",
    "amount": 50,
    "transactionId": "txn_h1rn8c9nd81y9bkgzax2k2rax"
}

Void

A Void cancels an existing transaction that has not yet settled. It can be run against a sale, an auth, or a drawdown.

For transactions that have already settled, use a Refund instead.

{
    "type": "void",
    "transactionId": "txn_h1rn8c9nd81y9bkgzax2k2rax"
}

Refund

A Refund returns the amount of a settled Sale or Capture to the customer. Because the original transaction must have settled first, a Refund can be performed no earlier than the next day.

For transactions that have not yet settled, use a Void instead.

Partial refund

To refund only part of a transaction, include an amount lower than the original. Only that amount is refunded. Partial refunds may be repeated, up to the remaining balance of the transaction.

{
    "type": "refund",
    "transactionId": "txn_h1rn8c9nd81y9bkgzax2k2rax"
}

{
    "type": "refund",
    "amount": 200,
    "transactionId": "txn_h1rn8c9nd81y9bkgzax2k2rax"
}