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

Permissions

token:use

Request

cURL

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

Parameter	Required	Type	Default	Description
amount	true	integer		Transaction amount in cents
connection_id	true	string		Connection to create this transaction with
currency	true	string		ISO-4217 currency code
country	false	string	null	2-letter ISO country code.
external_identifier	false	string	null	External identification returned in the completed transaction to match your records.
intent	false	string	null	Either authorize or capture to define the intent of this API call.
is_subsequent_payment	false	boolean	false	Set to true when transaction is from an on-going subscription.
merchant_initiated	false	boolean	false	Indicates whether the transaction was initiated by the merchant
metadata	false	object	null	Metadata key-values to store with the transaction.
payment_source	false	string	ecommerce	The payment source for the transaction.
previous_scheme_transaction_id	false	string	null	A 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_id	false	object	null	Identifier for Basis Theory 3DS Session.
token	true	uuid		Basis 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

Permissions

orchestration:transaction:capture

Request

cURL

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

Parameter	Required	Type	Description
transaction_id	true	uuid	Existing transaction id

Request Parameters

Parameter	Required	Type	Default	Description
amount	true	integer		The 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

Permissions

token:use

Request

cURL

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

Parameter	Required	Type	Description
transaction_id	true	uuid	Existing 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

Type	CVV	merchant_initiated	payment_source	is_subsequent_payment	previous_scheme_transaction_id
First transaction for a card	Commonly required	false	ecommerce	false	null
Express checkout / Card on File	Optional	false	card_on_file	false	null
Subscription (after first transaction)	Never	true	recurring	true	First transaction's scheme_transaction_id
Consumption-based	Never	true	card_on_file	false	First purchase scheme_transaction_id

Payment Sources

Source	Description
card_on_file	Used when utilizing a token without a CVC
ecommerce	Used on the first transaction when the CVC is present
recurring	Used 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

Parameter	Type	Default	Description
version	string		Ther version
status	object		The status of the 3DS challenge for this transaction. [setup_error, error, declined, cancelled, complete]
method	string		The method used for the 3DS challenge. [challenge, frictionless]
error_data	object		The error data for the 3DS challenge.

3DS Error Data Object

Parameter	Type	Default	Description
description	string		Description of the error returned by the ACS
detail	object		Details of the error returned from the ACS
code	string		The method used for the 3DS challenge. [challenge, frictionless]
component	object		The component within the 3DS flow that identified the error.

CVV Response Codes

Code	Description
no_match	the CVV does not match the expected value
match	the CVV matches the expected value
unavailable	CVV check unavailable for card our country
not_provided	CVV not provided

Transaction Object

Parameter	Type	Default	Description
id	string		Transaction Identifier
scheme_transaction_id	string		The scheme identifier to be used on additional transactions
payment_method	object		Payment method object.
connection	object		Connection used for the transaction.
amount	integer		The amount in cents for the transaction
currency	true	string
authorized_amount	integer		The amount authorized in cents for the transaction
captured_amount	integer		The amount captured in cents for the transaction
refunded_amount	integer		The amount refunded in cents for the transaction
country	string		2-letter ISO country.
external_identifier	string		External trans ID.
authorized_at	string		The date and time the transaction was authorized.
captured_at	string		The date and time the transaction was captured.
voided_at	string		The date and time the transaction was voided.
created_at	string		The date and time the transaction was created.
updated_at	string		The date and time the transaction was updated.
approval_expires_at	string		The date and time the transaction approval expires.
metadata	object		Metadata key-values stored with the transaction.
reconciliation_id	string		The 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_code	string		Error code for the transaction.
intent	string		The intent of the transaction.
intent_outcome	string		The outcome of the intent.
status	string		The status of the transaction.
connection_transaction_id	string		The transaction id from the underlying connection.
three_d_secure	object		3D Secure object.
auth_response_code	string		Authorization response code returned from the connection.
cvv_response_code	string		CVV response code returned from the connection.