Authorize and Capture

When to use it

A normal card charge collects the money right away. Authorize and capture splits that into two steps:

Authorize places a hold on the cardholder’s available credit. No money moves.
Capture collects the money, up to the amount you authorized.

Use it when the final amount isn’t known yet, or when you shouldn’t take payment until something happens first, such as an order shipping or a service being completed.

Authorize and capture works with credit cards only. The token needs the transaction:authorize-capture ability. Releasing a hold uses the void endpoint, which is gated separately by transaction:charge-card-token, so give the token both if you’ll ever need to release holds. See Authentication.

Step 1: Authorize

Send the amount and the card. You can supply the card in one of two ways:

A token from Tokenize a Credit Card. No PCI paperwork needed, because no card number is sent.
Raw card details: card_number, expiration_date (mm/YYYY), cardholder_name, and billing_address.zip. This requires PCI compliance, meaning an Attestation of Compliance on file with Dime Payments. Without one, the request is refused with 403 Merchant is not PCI Compliant.

Identify the customer with either phone (e.164 format, which creates or matches a customer) or customer_uuid.

curl --request POST \
  --url https://app.dimepayments.com/api/transaction/authorize \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": 1234567,
      "amount": 100.50,
      "token": "abc123def456",
      "phone": "+17701234567",
      "memo": "order 1234"
    }
  }'

A successful authorization returns transaction_status: Pending and status_text: APPROVAL. Save the transaction_number from the response. It’s your handle on the authorization for everything that follows. If the card is declined, you’ll get a 400 with status_code: 05 and status_text: DECLINE, and nothing is held.

Step 2: Capture

Pass the transaction_number from the authorization as data.transaction_id:

curl --request POST \
  --url https://app.dimepayments.com/api/transaction/capture \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": 1234567,
      "transaction_id": 1234567890,
      "amount": 87.25
    }
  }'

Leave out amount to capture the full authorized amount, or send a smaller amount to capture part of it.

An authorization can only be captured once. A partial capture settles that amount and releases the rest back to the cardholder. A second capture for the balance is refused with Transaction is not an open authorization. If you need to collect in more than one installment, such as a split shipment, authorize each installment separately.

Once captured, the payment behaves like any other card payment and can be refunded or voided.

Releasing a hold without charging

If the sale falls through, don’t capture. Void the authorization instead to release the hold right away:

curl --request PATCH \
  --url https://app.dimepayments.com/api/transaction/void \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": 1234567,
      "transaction_type": "CC",
      "transaction_id": "1234567890"
    }
  }'

transaction_type must be CC.

Timing

Capture promptly, ideally within 24 hours. An authorization that is never captured is released by the card issuer on its own schedule, and once it expires it can no longer be captured. If that happens, authorize again. If you authorized with a token and the token has expired, the request fails with 422 Token expired. Please retokenize, or provide the card details.

Errors

Status	Message	What it means
`400`	`DECLINE` (in `status_text`)	The card was declined on authorization
`400`	`Transaction is not an open authorization.`	Already captured, voided, or expired
`400`	`Amount cannot be greater than the authorized amount`	Capture amount exceeds the hold
`400`	`No transaction found.`	The `transaction_id` doesn’t match an authorization for this merchant
`400`	`Error processing capture`	The processor couldn’t complete the capture
`403`	`Merchant is not PCI Compliant`	Raw card details sent without an AoC on file. Use a token instead
`422`	`Token expired. Please retokenize, or provide the card details.`	Tokenize the card again

See Response Codes for permission and merchant errors common to every endpoint.

Next steps

Webhooks: Credit Card Authorize, Credit Card Capture, and Credit Card Void tell you when a hold is placed, collected, or released
API Reference: full request and response fields

Getting Started

SDKs

Payments

Going Live

Integrations

Reference

When to use it

Step 1: Authorize

Step 2: Capture

Releasing a hold without charging

Timing

Errors

Next steps

​When to use it

​Step 1: Authorize

​Step 2: Capture

​Releasing a hold without charging

​Timing

​Errors

​Next steps

When to use it

Step 1: Authorize

Step 2: Capture

Releasing a hold without charging

Timing

Errors

Next steps