Skip to main content

Transactions
Enterprise

Create Transaction

Attempts to create an authorization for a payment method. In some cases it is not possible to create the authorization without redirecting the user for their authorization. In these cases the status is set to indicate buyer approval is pending and an approval URL is returned.

You can find more information on how to use this endpoint for certain use-cases below.

POST
https://api.basistheory.com/orchestration/transactions
Copy

Permissions

token:use

Request

curl "https://api.basistheory.com/orchestration/transactions" \
-H "BT-API-KEY: <PRIVATE_API_KEY>"
-d '{
"connection_id": "f4c57207-ebd9-4909-af79-350d3d45392a",
"amount": 1299,
"currency": "USD",
"token": "",
}'

URI Parameters

ParameterRequiredTypeDefaultDescription
amounttrueintegerTransaction amount in cents
connection_idtruestringConnection to create this transaction with
currencytruestringISO-4217 currency code
countryfalsestringnull2-letter ISO country code.
external_identifierfalsestringnullExternal identification returned in the completed transaction to match your records.
intentfalsestringnullEither authorize or capture to define the intent of this API call.
is_subsequent_paymentfalsebooleanfalseSet to true when transaction is from an on-going subscription.
merchant_initiatedfalsebooleanfalseIndicates whether the transaction was initiated by the merchant
metadatafalseobjectnullMetadata key-values to store with the transaction.
payment_sourcefalsestringecommerceThe payment source for the transaction.
previous_scheme_transaction_idfalsestringnullA scheme's transaction identifier to use in connecting a merchant initiated transaction to a previous customer initiated transaction. This is returned as scheme_transaction_id on each transaction response.
three_d_session_idfalseobjectnullIdentifier for Basis Theory 3DS Session.
tokentrueuuidBasis Theory Card Token used as the payment method

Response

Returns a transaction object if the transaction was created with the connection. Returns an error if there were validation errors before a transaction could be created.

{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"authorized_amount": 1299,
"authorized_at": "2013-07-16T19:23:00.000+00:00",
...
}

Capture Transaction

POST
https://api.basistheory.com/orchestration/transactions/{id}/capture
Copy

Permissions

orchestration:transaction:capture

Request

curl "https://api.basistheory.com/orchestration/transactions/c06d0789-0a38-40be-b7cc-c28a718f76f1/capture" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"amount": 1490,
}'

URL Parameters

ParameterRequiredTypeDescription
transaction_idtrueuuidExisting transaction id

Request Parameters

ParameterRequiredTypeDefaultDescription
amounttrueintegerThe monetary amount to capture an authorization for, in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99. When omitted blank, this will capture the entire amount.

Response

Returns a transaction object if the transaction was captured. Returns an error if there were validation errors before a transaction could be created.

{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"authorized_amount": 1299,
"authorized_at": "2013-07-6T19:23:00.000+00:00",
..
}

Void Transaction

POST
https://api.basistheory.com/orchestration/transactions/{id}/void
Copy

Permissions

token:use

Request

curl "https://api.basistheory.com/orchestration/transactions/c06d0789-0a38-40be-b7cc-c28a718f76f1/void" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \

URL Parameters

ParameterRequiredTypeDescription
transaction_idtrueuuidExisting transaction id

Response

Returns a transaction object if the transaction was voided. Returns an error if there were validation errors before a transaction could be created.

{
"type": "transaction",
"id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
"amount": 1299,
"authorized_amount": 1299,
"authorized_at": "2013-07-16T19:23:00.000+00:00",
...
}

Resources

Common Transaction Use-cases

TypeCVVmerchant_initiatedpayment_sourceis_subsequent_paymentprevious_scheme_transaction_id
First transaction for a cardCommonly requiredfalseecommercefalsenull
Express checkout / Card on FileOptionalfalsecard_on_filefalsenull
Subscription (after first transaction)NevertruerecurringtrueFirst transaction's scheme_transaction_id
Consumption-basedNevertruecard_on_filefalseFirst purchase scheme_transaction_id

Payment Sources

SourceDescription
card_on_fileUsed when utilizing a token without a CVC
ecommerceUsed on the first transaction when the CVC is present
recurringUsed when the transaction from an on-going subscription

Statuses

Status
processing
buyer_approval_pending
authorization_succeeded
authorization_failed
authorization_declined
capture_pending
capture_succeeded
authorization_void_pending
authorization_voided

3DS Object

ParameterTypeDefaultDescription
versionstringTher version
statusobjectThe status of the 3DS challenge for this transaction. [setup_error, error, declined, cancelled, complete]
methodstringThe method used for the 3DS challenge. [challenge, frictionless]
error_dataobjectThe error data for the 3DS challenge.

3DS Error Data Object

ParameterTypeDefaultDescription
descriptionstringDescription of the error returned by the ACS
detailobjectDetails of the error returned from the ACS
codestringThe method used for the 3DS challenge. [challenge, frictionless]
componentobjectThe component within the 3DS flow that identified the error.

CVV Response Codes

CodeDescription
no_matchthe CVV does not match the expected value
matchthe CVV matches the expected value
unavailableCVV check unavailable for card our country
not_providedCVV not provided

Transaction Object

ParameterTypeDefaultDescription
idstringTransaction Identifier
scheme_transaction_idstringThe scheme identifier to be used on additional transactions
payment_methodobjectPayment method object.
connectionobjectConnection used for the transaction.
amountintegerThe amount in cents for the transaction
currencytruestring
authorized_amountintegerThe amount authorized in cents for the transaction
captured_amountintegerThe amount captured in cents for the transaction
refunded_amountintegerThe amount refunded in cents for the transaction
countrystring2-letter ISO country.
external_identifierstringExternal trans ID.
authorized_atstringThe date and time the transaction was authorized.
captured_atstringThe date and time the transaction was captured.
voided_atstringThe date and time the transaction was voided.
created_atstringThe date and time the transaction was created.
updated_atstringThe date and time the transaction was updated.
approval_expires_atstringThe date and time the transaction approval expires.
metadataobjectMetadata key-values stored with the transaction.
reconciliation_idstringThe base62 encoded transaction ID. This represents a shorter version of this transaction's id which is sent to payment services, anti-fraud services, and other connectors. You can use this ID to reconcile a payment service's transaction against our system.
error_codestringError code for the transaction.
intentstringThe intent of the transaction.
intent_outcomestringThe outcome of the intent.
statusstringThe status of the transaction.
connection_transaction_idstringThe transaction id from the underlying connection.
three_d_secureobject3D Secure object.
auth_response_codestringAuthorization response code returned from the connection.
cvv_response_codestringCVV response code returned from the connection.