Authorizing a Card Payment

After tokenizing a card, submit the token to create a payment authorization. You can choose between:

Pre-authorization ("capture": false) — Reserves funds without settling. You capture later when ready.
Direct capture ("capture": true) — Authorizes and captures in one step. Funds are settled immediately.

Understanding Pre-Authorization vs. Direct Capture

This is one of the most commonly misunderstood concepts in card payments. Getting it right determines how much control you have over your money flow — and how quickly you can reverse a transaction if something goes wrong.

What is pre-authorization?

When you set "capture": false, the gateway asks the cardholder's bank to reserve the funds on their card — but no money moves yet. The cardholder sees a "pending" charge on their statement, but settlement (the actual transfer of funds to your account) does not happen until you explicitly capture the payment.

Think of it as placing a hold on the funds. The money is still in the cardholder's account, but they can't spend it elsewhere.

Why use pre-authorization?

Pre-authorization gives you a window to perform additional checks before committing to the financial settlement:

AVS / CVC verification — Review the address and security code results from the authorization response. If they indicate fraud risk, you can cancel immediately.
Anti-fraud analysis — Run the transaction through your fraud scoring system, manual review queues, or third-party fraud tools.
Inventory / fulfillment checks — Confirm the item is in stock, the service is available, or any business-specific validation passes.
Compliance / KYC — Verify the customer meets regulatory requirements before finalizing the transaction.
Order adjustments — The final amount may differ from the initial hold (e.g., partial shipments). You can capture a smaller amount than authorized.

The key advantage: fast, clean reversal

If you need to cancel a pre-authorized transaction, you perform a void. A void instantly releases the hold on the cardholder's funds — typically within minutes. The cardholder sees the pending charge disappear from their statement. No money was ever moved, so there's nothing to "return."

Compare this to what happens after capture: once a transaction is captured, settlement has occurred. The money has left the cardholder's account and landed in yours. The only way to return funds at that point is a refund, which is a separate financial transaction that can take 3–10 business days to appear on the cardholder's statement.

Side-by-side comparison

	Pre-authorization (`capture: false`)	Direct capture (`capture: true`)
What happens	Funds are held (reserved) on the card	Funds are held AND settled immediately
Money moves?	❌ No — just a hold	✅ Yes — settlement begins
To cancel	Void — instant, no money moved	Refund — separate transaction, 3–10 days
Cardholder sees	"Pending" charge	Completed charge
Time limit	Must capture within 7 days or the hold expires automatically	N/A — already captured
Can adjust amount?	✅ Capture less than authorized	❌ Amount is final
Best for	E-commerce, travel, subscriptions, anything needing review	Simple point-of-sale, instant digital goods

When to use which

Use pre-authorization (capture: false) when:

You need time to verify fraud signals, AVS/CVC results, or compliance
The final amount might change (partial shipments, tips, hotel incidentals)
You want the ability to cancel cleanly without a refund hitting the cardholder's statement
Your fulfillment has any delay between payment and delivery

Use direct capture (capture: true) when:

The transaction is final and immediate (digital download, in-store purchase)
No review or adjustment is needed
You want the simplest integration with fewer API calls

The lifecycle at a glance

                 capture: false                    capture: true
                 ─────────────                     ─────────────
POST /v2/payment                          POST /v2/payment
       │                                         │
       ▼                                         ▼
   AUTHORIZED                                CAPTURED
   (funds held)                              (funds settled)
       │                                         │
   ┌───┴───┐                                     ▼
   │       │                                  REFUNDED
   ▼       ▼                               (3-10 days to
CAPTURED  VOIDED                            cardholder)
(settle)  (release hold,
   │       instant)
   ▼
REFUNDED
(3-10 days)

Bottom line: If there's any chance you might need to cancel the transaction after authorization, use pre-authorization. It's faster to reverse, cleaner for the cardholder, and gives you full control over the settlement timing.

Endpoint

POST https://{FQDN}/v2/payment

Headers:

Header	Value
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Request Body

Root Object

Field	Type	Required	Description
`externalPaymentId`	string	✅	Your unique identifier for this payment (idempotency key)
`ipAddress`	string	✅	Payer's IPv4 or IPv6 address
`paymentType`	string	✅	`"PULL"`
`capture`	boolean	✅	`true` = auto-capture; `false` = pre-auth only
`amount`	object	✅	Transaction amount
`sender`	object	✅	Payer details

`amount` Object

Field	Type	Required	Description
`total`	number	✅	Amount to charge (must be ≥ 1)
`currency`	string	✅	ISO 4217 currency code (e.g., `"USD"`)

`sender` Object

Field	Type	Required	Description
`firstName`	string	✅	Payer's first name
`lastName`	string	✅	Payer's last name
`address`	object	✅	Billing address (used for AVS verification)
`paymentMethod`	object	✅	Card token details

`sender.address` Object

Field	Type	Required	Description
`countryCode`	string	✅	ISO Alpha-3 country code (e.g., `"USA"`)
`stateCode`	string	✅	State/province abbreviation (e.g., `"NY"`)
`city`	string	✅	City name
`line1`	string	✅	Street address line 1
`line2`	string	❌	Street address line 2
`zipCode`	string	✅	Postal/ZIP code

`sender.paymentMethod` Object (Card)

Field	Type	Required	Description
`type`	string	✅	`"CARD"`
`cardTokenId`	string	✅	Token UUID from the tokenizer
`previousPaymentId`	string	❌	Required for recurring tokens — the `paymentId` from the initial authorization

Example Request

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "order-12345",
    "ipAddress": "203.0.113.42",
    "paymentType": "PULL",
    "capture": false,
    "amount": {
      "total": 99.99,
      "currency": "USD"
    },
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "countryCode": "US",
        "stateCode": "NY",
        "city": "New York",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "zipCode": "10001"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
      }
    }
  }'

Response

Successful Authorization (200)

{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "parentPaymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "created": "2025-03-31 03:49:05",
    "approved": true,
    "message": "Payment Approved",
    "automaticReversed": false,
    "status": "AUTHORIZED",
    "captured": false,
    "voided": false,
    "responseCode": "00",
    "issuerName": "BANK OF AMERICA",
    "issuerCountry": "UNITED STATES",
    "cvcResult": "APPROVED",
    "avsResult": "APPROVED",
    "avsCardholderNameResult": "N/A",
    "avsTelephoneResult": "N/A"
  }
}

3DS Challenge Required (200)

When the issuing bank requires cardholder verification, the response returns status: "CHALLENGE" with a redirectAcsUrl:

{
  "status": 200,
  "data": {
    "paymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8",
    "externalPaymentId": "order-12345",
    "redirectAcsUrl": "https://{FQDN}/secure-code/start-challenge?token=dce568c6-...",
    "amount": 99.99,
    "approved": false,
    "message": "Payment awaiting 3DS challenge verification",
    "status": "CHALLENGE",
    "captured": false,
    "voided": false,
    "responseCode": "00",
    "cvcResult": "N/A",
    "avsResult": "N/A"
  }
}

When you receive CHALLENGE, redirect the cardholder to redirectAcsUrl. See Handling 3D Secure for the complete flow.

Declined (400)

{
  "status": 400,
  "data": {
    "paymentId": "abc12345-...",
    "externalPaymentId": "order-12345",
    "amount": 99.99,
    "approved": false,
    "message": "Not sufficient funds",
    "status": "DECLINED",
    "responseCode": "PAY_084"
  }
}

Response Fields

Field	Type	Description
`paymentId`	string	Inyo's unique payment identifier
`parentPaymentId`	string	Parent payment ID (same as `paymentId` for initial authorizations)
`externalPaymentId`	string	Your original external ID
`redirectAcsUrl`	string	3DS challenge URL (only present when `status` = `CHALLENGE`)
`amount`	number	Transaction amount
`created`	string	Timestamp (EST)
`approved`	boolean	`true` if authorized successfully
`message`	string	Human-readable status message
`automaticReversed`	boolean	`true` if payment was auto-reversed by fraud rules
`status`	string	`AUTHORIZED`, `CHALLENGE`, or `DECLINED`
`captured`	boolean	`true` if auto-captured (`"capture": true` in request)
`voided`	boolean	`true` if voided
`responseCode`	string	Issuer/gateway response code (see Response Codes)
`issuerName`	string	Name of the issuing bank
`issuerCountry`	string	Country of the issuer
`cvcResult`	string	`APPROVED`, `FAILED`, `NOT_SENT`, or `N/A`
`avsResult`	string	`APPROVED`, `FAILED`, `NOT_SENT`, or `N/A`

Using a Recurring Token

If the card was tokenized with storeLaterUse: true, you can reuse the token for future charges by including the previousPaymentId:

{
  "sender": {
    "paymentMethod": {
      "type": "CARD",
      "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe",
      "previousPaymentId": "dce568c6-98ec-456c-bb33-4a6809c4fff8"
    }
  }
}

What's Next

Authorized? → Capture the payment when ready to settle
Need to cancel? → Void the authorization before capture
3DS Challenge? → Handle 3D Secure redirect flow
Check verification? → AVS / CVC results